Skip to main content

Code Environment

In Bosun, a "code environment" is the isolated space where your automated tasks, specifically the code written or modified by agents, are executed. This environment provides a secure and consistent setting for all operations.

Here are the key characteristics of a Bosun code environment:

  • Universal Docker Images: Each task runs within a standardized Docker image. These images come pre-equipped with common development tools and runtimes—including Node.js, Ruby, Rust, Java, Bun, Python, and PHP support—so agents have what they need without extra setup.

  • External Communication: The code environment can communicate with the external world. This means agents can make outbound network calls to interact with APIs, fetch data, or perform Git operations on your connected repository.

  • Service Environment Isolation: Service-level environment variables that Bosun manages (for example, credentials used to bring services online) do not leak into task execution. Agents only see the task inputs and environment variables you explicitly provide.

  • Isolated Execution: Every code environment is strictly isolated. This prevents any interaction or interference between different tasks running concurrently or with the Bosun platform itself, ensuring security and reliability.

  • CI-aware defaults: Executors export CI=true for every run. Tooling that switches behavior when it detects CI (for example, npm, Playwright, or custom scripts) therefore behaves consistently without needing extra configuration.

  • Stateful executor with encrypted storage: Tasks run on a Kubernetes-backed, single-replica StatefulSet. Each run gets its own encrypted persistent volume so retries keep the same workspace, and the same volume is reattached if the pod restarts or is rescheduled mid-run.

  • Ephemeral Lifecycle: Even though the executor is stateful during a run, Bosun tears everything down (pod, PVC, secrets) once the workflow stops or hits the 24‑hour ceiling. Nothing lingers between customer runs, and cleanup wipes the workspace before deleting the PVC.

  • Additional Services: You can define additional services (like databases or caches) to run alongside your code environment. These services are isolated from the Bosun platform and can be configured via a .bosun/config.toml file in your repository.

This setup provides a robust and secure sandbox for your automated workflows, allowing agents to operate effectively while maintaining strict boundaries.

Customising​

You can tailor each run in two layers:

  1. Repository defaults from .bosun/config.toml – great for settings you want every run to inherit (services, env vars, setup scripts, tool timeouts, etc.).
  2. Runtime overrides supplied when starting a run – perfect when a single execution needs a different test command, temporary env var, or a one-off service.

Repository defaults via .bosun/config.toml​

The environment can be customized by providing a .bosun/config.toml in your repository. You can provide services that will be started alongside the code environment, and you can provide environment variables that will be available.

Bosun always injects CI=true, even if you do not request it. You can override or remove it by defining CI inside code-environment.env (or through overrides described below), but most users keep the default so automated test suites stay aligned with normal CI expectations.

An example:

setup_script = """#!/usr/bin/env bash
set -euo pipefail
pnpm install
"""

[code-environment.env]
DATABASE_URL = "postgres://postgres:password@localhost:5432/test"
RAILS_ENV = "test"
RUST_LOG = "debug"

[code-environment.services.postgres]
image = "postgres:15-alpine"
env = { POSTGRES_USER = "postgres", POSTGRES_PASSWORD = "password", POSTGRES_DB = "test" }
options = """
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
"""
[code-environment.services.qdrant]
image = "qdrant/qdrant:v1.15"

[code-environment.services.redis]
image = "redis:7-alpine"

Bosun runs the setup_script in the repository root before any run or agent step executes. Use that hook to encode whatever instructions your AGENTS.md lays out, then keep the script idempotent and add validation checks before the task runs.

danger

Environment variables defined in the code-environment.env are meant for non-sensitive configuration only. You can add secrets via the Bosun UI. These are encrypted, scrubbed from agents and logs, and injected at runtime in the environment.

Runtime overrides from the app or API​

When you configure a task run in the Bosun app, expand Repository overrides and edit the commands, environment variables, services, or setup script for that run. These edits are stored alongside the launch request and merged in the following order:

  1. Task-run overrides chosen in the app (or sent through the API)
  2. Saved repository overrides (Projects → Repositories → Configure overrides)
  3. .bosun/config.toml that lives in the repository

Leave the Update repository defaults checkbox off to keep the change scoped to that single run. Turn it on when you want to persist the merged configuration back to the repository record.

All four sections are optional—send only what you need to override. The payload mirrors the .bosun/config.toml structure, so you can promote a known-good config from the repo file to a one-off task override (or vice versa) without relearning new keys.

Stateful executor, storage, readiness, and cleanup​

Bosun launches each task via a dedicated Kubernetes StatefulSet:

  • Encrypted persistent volumes: The executor mounts a PVC sized according to the platform defaults (20 GiB today). When the pod restarts or is rescheduled mid-run, the same volume is reattached so cached dependencies and build artifacts stay available throughout the run. Once the workflow finishes, the executor wipes the workspace and deletes the PVC so no customer code remains in the cluster.
  • Automatic cleanup: As soon as the workflow completes successfully—or hits the 24-hour ceiling—Bosun tears down the pod, StatefulSet, PVC, and execution secrets. Cleanup is automatic, so clusters do not accumulate idle executor resources.
  • Graceful startup window: The scheduler waits up to 15 minutes for the executor pod (and any declared services) to become Ready before it fails the task. This protects long-lived database sidecars and avoids spurious failures when clusters need to scale nodes.

Resource limits and timeouts​

Kubernetes executions default to 2 vCPUs (2000 millicores), 4 GiB of RAM, and the 20 GiB encrypted workspace mentioned above. These limits cover most repository-scale refactors; reach out to Bosun support if your organization needs higher ceilings so we can tune them for your tenancy.

Command execution has clear limits as well:

  • Default command timeout: Every run step and every tool that shells out inherits a 5‑minute timeout. Agents automatically retry within that window, and Bosun surfaces the timeout in the run view if a command exceeds it.

  • ANSI-clean output: The shell_command tool strips ANSI escape sequences from stdout and stderr before Bosun stores or streams the result. Logs stay readable in the session view, and any downstream parsing works with plain text instead of terminal color codes.

Remember that secrets you store through Projects → Repositories → Configure → Secrets are materialized as environment variables inside the executor. Use those variables directly in .bosun/config.toml (e.g., gitlab_api_key = "env:GITLAB_PAT") or in your manifests without hard-coding sensitive strings.These secrets are encrypted at rest and in transit, and never appear in logs, and scrubbed from agent context and logs.