Cloud Sandbox Host

A cloud sandbox host moves the Omnigent runner from your laptop to a remote container. Your agent keeps working after you close your laptop, in an isolated environment with cloud compute.

Omnigent currently supports Modal, Daytona, Blaxel, and Islo as hosting platforms for cloud sandbox hosts, with more on the way.

Server-managed (recommended)

Configure your server once and anyone on the team can launch a cloud sandbox host from the web UI.

1. Install

pip install 'omnigent[modal]'       # for Modal
pip install 'omnigent[daytona]'     # for Daytona
pip install 'omnigent[blaxel]'      # for Blaxel
pip install 'omnigent[islo]'        # for Islo

The Islo launcher uses the Islo Python SDK, which ships in the omnigent[islo] extra and is imported lazily, so only users of the Islo provider need to install it. The omnigent[blaxel] extra ships the Blaxel Python SDK with the same lazy-import posture. To launch Blaxel sandboxes from the CLI you also need the Blaxel CLI (brew tap blaxel-ai/blaxel && brew install blaxel).

2. Set provider credentials

Modal: run modal setup to authenticate, or set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET on the server.

Daytona: create an API key in the Daytona dashboard (Dashboard > Keys) and set it on the server:

export DAYTONA_API_KEY=dtn_…

Islo: create an API key with the Islo CLI (islo login, then islo api-key create omnigent --show) and set it on the server. The SDK exchanges the key for short-lived session tokens and refreshes them automatically, so the API key is the only required runtime credential:

export ISLO_API_KEY=islo_key_…
# export ISLO_BASE_URL=https://api.islo.dev      # optional, non-default API endpoint
# export ISLO_COMPUTE_URL=…                       # optional, non-default compute endpoint

Blaxel: log in to your workspace with the Blaxel CLI (bl login your-workspace), or set the control credentials on the server for a non-interactive process:

export BL_WORKSPACE=your-workspace
export BL_API_KEY=your-api-key

Blaxel control credentials must stay on the launching process (your shell for a CLI launch, the server for a managed launch) and never enter the sandbox. Web users log in to Omnigent, not Blaxel.

3. Configure the cloud sandbox host

Add a sandbox section to your server config YAML (~/.omnigent/config.yaml on a laptop, /data/config.yaml in Docker). This is the same file where you define server-wide policies.

Only provider and server_url are required. The provider block is optional.

Modal:

sandbox:
  provider: modal
  server_url: https://your-server.example.com
  modal:
    image: ghcr.io/omnigent-ai/omnigent-host:latest  # optional, official image by default
    secrets: [omnigent-llm]                        # Modal secrets with LLM API keys

secrets injects Modal secrets (API keys, gateway URLs) into the cloud sandbox host. Values stay in Modal's secret store.

Daytona:

sandbox:
  provider: daytona
  server_url: https://your-server.example.com
  daytona:
    image: docker.io/you/omnigent-host:latest      # optional, official image by default
    env: [OPENAI_API_KEY, ANTHROPIC_API_KEY]        # server env vars to copy into sandbox

env lists env var names to copy from the server's environment into each cloud sandbox host. Values never live in the config file. A listed variable that isn't set fails the launch loudly.

Islo:

sandbox:
  provider: islo
  server_url: https://your-server.example.com
  islo:
    image: ghcr.io/omnigent-ai/omnigent-host:latest  # optional, official image by default
    env: [OPENAI_API_KEY, ANTHROPIC_API_KEY]         # server env vars to copy into sandbox
    idle_pause_after_s: 900                          # optional; null disables idle pause

Blaxel:

sandbox:
  provider: blaxel
  server_url: https://your-server.example.com    # must be a public URL Blaxel can reach
  blaxel:
    image: blaxel/omnigent-host:TAG                # optional; default: blaxel/omnigent-host:latest
    env: [OPENAI_API_KEY, ANTHROPIC_API_KEY]       # server env vars to copy into sandbox
    region: us-was-1                               # optional; default: BL_REGION or Blaxel default
    memory_mb: 4096                                # optional; default: 4096
    ttl: 24h                                       # optional; default maximum age: 24h

Blaxel uses the public blaxel/omnigent-host:latest image, which combines the standard Omnigent host runtime with Blaxel's required sandbox-api. Pin a fixed published tag with image or the OMNIGENT_BLAXEL_HOST_IMAGE env var. All managed sandboxes use the server process's Blaxel workspace and credentials; Omnigent users are not mapped to individual Blaxel workspaces.

OpenShell:

sandbox:
  provider: openshell
  server_url: https://your-server.example.com
  openshell:
    image: ghcr.io/omnigent-ai/omnigent-host:latest  # optional, official image by default
    env: [OPENAI_API_KEY, ANTHROPIC_API_KEY]         # server env vars to copy into sandbox
    cluster: my-gateway                              # optional OpenShell gateway name
    workspace: team-alpha                            # optional; defaults to "default"

cluster selects the OpenShell gateway to connect to; omit it to use the active gateway ($OPENSHELL_GATEWAY or ~/.config/openshell/active_gateway). workspace is the OpenShell workspace used for sandbox lifecycle operations (create, get, delete). Omit it to resolve $OMNIGENT_OPENSHELL_WORKSPACE, then fall back to "default".

Boxlite:

sandbox:
  provider: boxlite
  server_url: https://your-server.example.com
  boxlite:
    image: docker.io/me/omnigent-host:latest     # optional, official image by default
    env: [OPENAI_API_KEY, GIT_TOKEN]             # server env vars to copy into sandbox
    disk_size_gb: 100                            # optional; box disk size in GB
    cloud:
      endpoint: https://boxlite.example.com:8100 # selects CLOUD mode
    # local: {home_dir: /data/boxlite, registry: {...}}  # LOCAL mode (default if omitted)

env lists env var names to copy from the server's environment into each box; values never live in the config file. Provide exactly one mode: a cloud block with an endpoint (CLOUD mode, authenticated with the BOXLITE_API_KEY env var), or a local block with home_dir / registry (LOCAL mode, used by default when neither is set).

disk_size_gb sets the box disk size in gigabytes and must be a positive integer. Omit it to use the Boxlite SDK's own default disk size.

Inject provider config into sandboxes (optional)

An optional top-level host_config under sandbox: (provider-agnostic — not inside a provider block like modal: or daytona:) holds verbatim in-sandbox ~/.omnigent/config.yaml content that the server installs into each sandbox before omnigent host starts. The common use is a providers: block that routes a harness through a self-hosted gateway (for example LiteLLM or vLLM):

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

The block is server-managed: entries injected by a previous launch are replaced or removed on the next launch or resume, so each sandbox always reflects the current config. Config created inside the sandbox under names the server never injects survives untouched.

Keep secrets out of host_config. Reference credentials with api_key_ref: env:VAR — the variable is resolved inside the sandbox against its own environment (the provider's credential lane, such as Modal secrets or copied env vars), never on the server. An inline api_key is rejected at server startup. The host_config block (and its providers: shape) is validated when the server starts, so a typo fails loudly instead of degrading silently inside the sandbox.

4. Launch from the web UI

Start a new session and select New Sandbox in the host picker. The server provisions the cloud host, starts the runner, and connects it back automatically. This works the same on both hosting platforms.

CLI

Create and manage cloud sandbox hosts from the command line. The commands are the same across hosting platforms, just switch the --provider flag.

omni sandbox create --provider modal          # or --provider daytona / blaxel / islo
omni sandbox connect --provider modal \
  --sandbox-id <id> --server <url>

For a Blaxel CLI launch, list any credentials the host or agent needs in OMNIGENT_BLAXEL_SANDBOX_ENV (a comma-separated list of server env var names) before create — never include BL_API_KEY or BL_CLIENT_CREDENTIALS. Blaxel does not expose local callback port forwarding, so the in-sandbox browser login is skipped automatically. Stopping connect leaves the sandbox running; delete it with bl delete sandbox <id> or from the Blaxel console.