Cloud sandbox configuration

The server can provision remote runner hosts through several sandbox providers. See Cloud Sandbox Host for installation, provider authentication, and launch steps.

Common settings

Add the top-level sandbox block to the server configuration:

sandbox:
  provider: modal
  server_url: https://your-server.example.com

Provider-specific blocks are optional. Omit one to use that provider's defaults.

Modal

sandbox:
  provider: modal
  server_url: https://your-server.example.com
  modal:
    image: ghcr.io/omnigent-ai/omnigent-host:latest
    secrets: [omnigent-llm]

• image defaults to the official Omnigent host image.
• secrets names Modal secrets to inject into the runner. Values remain in Modal's secret store.

Daytona

sandbox:
  provider: daytona
  server_url: https://your-server.example.com
  daytona:
    image: docker.io/you/omnigent-host:latest
    env: [OPENAI_API_KEY, ANTHROPIC_API_KEY]

• image defaults to the official Omnigent host image.
• env lists server environment variables copied into each sandbox. A listed variable that is not set fails the launch.

Daytona Tier 1 and 2 organizations restrict outbound traffic to a fixed allowlist. The server_url and model endpoints must be reachable from Daytona. Tier 3 and higher lift that restriction. On the free tier, use a Cloudflare Worker relay on the allowlisted *.workers.dev domain; the repository includes an example under deploy/daytona/. Modal has full egress on its entry tier.

Islo

sandbox:
  provider: islo
  server_url: https://your-server.example.com
  islo:
    image: ghcr.io/omnigent-ai/omnigent-host:latest
    env: [OPENAI_API_KEY, ANTHROPIC_API_KEY]
    idle_pause_after_s: 900

• image defaults to the official Omnigent host image.
• env lists server environment variables copied into each sandbox. A listed variable that is not set fails the launch.
• idle_pause_after_s defaults to 900. Set it to null to disable idle pause.

When a new message arrives for a paused Islo host, Omnigent resumes the same sandbox and restarts the runner. Changing idle_pause_after_s affects new sandboxes, not existing ones. Deleting the session still deletes the sandbox.

The provider uses ISLO_API_KEY. ISLO_BASE_URL and ISLO_COMPUTE_URL can override its service endpoints.

Blaxel

sandbox:
  provider: blaxel
  server_url: https://your-server.example.com
  blaxel:
    image: blaxel/omnigent-host:latest
    env: [OPENAI_API_KEY, ANTHROPIC_API_KEY]
    region: us-was-1
    memory_mb: 4096
    ttl: 24h

• image defaults to blaxel/omnigent-host:latest.
• env lists server environment variables copied into each sandbox.
• region defaults to BL_REGION or the Blaxel default.
• memory_mb defaults to 4096.
• ttl defaults to 24h and accepts w, d, h, m, and s, alone or combined, such as 1h30m.

ttl is the sandbox's maximum age from creation, not an idle timeout. Blaxel deletes the sandbox at that age even while its session is active. The launch token lasts for ttl + 1h; provider command output is capped at 4 MiB.

The default image combines the Omnigent host runtime with Blaxel's required sandbox-api. Pin a published tag with image when deployments must remain stable across releases.

Managed sandboxes use the server process's Blaxel workspace and credentials. Omnigent users are not mapped to individual Blaxel workspaces. Set OMNIGENT_BLAXEL_HOST_IMAGE to override the default image without changing the configuration. The Blaxel SDK's telemetry is disabled; keep DO_NOT_TRACK=1 set on the server to preserve that behavior.

OpenShell

sandbox:
  provider: openshell
  server_url: https://your-server.example.com
  openshell:
    image: ghcr.io/omnigent-ai/omnigent-host:latest
    env: [OPENAI_API_KEY, ANTHROPIC_API_KEY]
    cluster: my-gateway
    workspace: team-alpha

• image defaults to the official Omnigent host image.
• env lists server environment variables copied into each sandbox.
• cluster defaults to the active OpenShell gateway from $OPENSHELL_GATEWAY or ~/.config/openshell/active_gateway.
• workspace defaults to $OMNIGENT_OPENSHELL_WORKSPACE, then default.

When a server-managed OpenShell sandbox goes dormant, its persistent volume is retained and the session reports a wakeable "asleep" state. The next message resumes the same sandbox in place, preserving its name and volume, and waits for it to become ready before continuing.

In-place resume requires SandboxClient.start, added in openshell 0.0.105. With an older SDK, the host remains offline instead of advertising an unsupported wake action; upgrade with uv pip install --upgrade 'omnigent[openshell]'. Resume is currently a cold restart rather than a warm snapshot restore.

Microsandbox

The microsandbox provider runs each managed session in a micro-VM on the same machine as the server. Because the guest runs untrusted agent code next to the server, its default host network mode exposes only an explicit TCP port allowlist rather than the entire host.

sandbox:
  provider: microsandbox
  server_url: http://host.microsandbox.internal:8317
  microsandbox:
    host_ports: [8317]

host.microsandbox.internal is the stable guest hostname for the machine running microsandbox. In host network mode:

• The server_url port is added to the host allowlist only when server_url targets host.microsandbox.internal. A public server_url does not implicitly open the matching port on the host.
• List any additional host-local services the guest needs in host_ports, using integer ports from 1 through 65535. Everything else on the host remains unreachable.

Boxlite

sandbox:
  provider: boxlite
  server_url: https://your-server.example.com
  boxlite:
    image: docker.io/me/omnigent-host:latest
    env: [OPENAI_API_KEY, GIT_TOKEN]
    disk_size_gb: 100
    cloud:
      endpoint: https://boxlite.example.com:8100

• image defaults to the official Omnigent host image.
• env lists server environment variables copied into each sandbox.
• disk_size_gb must be a positive integer. Omit it to use the SDK default.

Provide one mode: cloud.endpoint selects cloud mode and uses BOXLITE_API_KEY; local.home_dir and local.registry configure local mode. Local mode is used when neither block is set.

Gensee

Gensee is a managed-host provider only. The server talks to the Gensee control plane over HTTPS; no cloud-provider credentials or Gensee implementation packages are installed in Omnigent. Creating a managed session allocates one sandbox, has its control plane start omnigent host, and waits for that host to connect back. Gensee does not implement omnigent sandbox create, remote exec/file-copy primitives, stopped-sandbox resume, or workspace fork/merge.

The production endpoint and standard token variable are defaults, so the minimal configuration is just provider + server_url:

sandbox:
  provider: gensee
  server_url: https://your-server.example.com

Use an explicit block for a dedicated or development endpoint:

sandbox:
  provider: gensee
  server_url: https://your-server.example.com
  gensee:
    endpoint: https://sandbox.gensee.ai
    api_token_env: GENSEE_CONTROLLER_API_TOKEN
    workspace_root: /mnt/gensee-tclone/workspaces
    operation_timeout_s: 900
    poll_interval_s: 2
    request_timeout_s: 40
    retry_timeout_s: 60
    env: []

The endpoint must use HTTPS and cannot contain credentials, a query, or a fragment. Unknown settings and malformed values stop server startup rather than failing on the first user session.

GENSEE_CONTROLLER_URL overrides the default endpoint when constructing the launcher directly. An explicit sandbox.gensee.endpoint takes precedence in the server-managed configuration.

The Gensee API token stays in the server and authorizes lifecycle requests. Each sandbox receives a separate server-minted Omnigent host token (valid for seven days) through Gensee's short-lived secret store; it is not included in the durable operation request. By default no model or Git credentials are injected — list only variables every sandbox on the server may receive in env, or leave it empty and let each user sign in from their own sandbox terminal.

Native harness bridge servers

Native harnesses (for example claude-native) run small HTTP servers on the sandbox host — a tool relay and an MCP control ingress — that the harness's hook and helper subprocesses call back into. By default these bind loopback only (127.0.0.1), so an ordinary host keeps them off every other interface.

A sandbox whose SSRF hardening denies loopback destinations unconditionally (the openshell provider is one such backend) cannot reach a loopback-advertised relay, so every prompt fails closed. Opt into an all-interfaces bind by setting OMNIGENT_BRIDGE_BIND_HOST=0.0.0.0 in the sandbox host environment: the servers then listen on all interfaces (loopback consumers keep working) and advertise the host's routable address so the in-sandbox hooks can reach them.

Bridge servers draw their ports from a small stable pool (28700–28715 by default) so a sandbox network policy can allowlist them by exact host and port. Several servers coexist per host — the MCP ingress plus one tool relay per session — so allowlist the whole pool, not a single port. When the pool is exhausted the servers fall back to an OS-assigned ephemeral port, which an exact-port policy cannot cover.

Host configuration

The provider-independent host_config block contains the ~/.omnigent/config.yaml content installed inside each sandbox before omnigent host starts:

sandbox:
  provider: modal
  server_url: https://your-server.example.com
  host_config:
    providers:
      litellm:
        kind: gateway
        default: [pi]
        openai:
          base_url: http://litellm.litellm.svc.cluster.local/v1
          api_key_ref: env:LITELLM_API_KEY
          wire_api: chat

On launch or resume, the server replaces or removes entries that it previously injected. Configuration created inside the sandbox under other names remains untouched.

Do not put secrets in host_config. Use api_key_ref: env:VAR; the variable is resolved inside the sandbox from its provider-specific credential source. Inline api_key values are rejected. The server validates the block at startup.