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 Databricks Sandbox, Modal, Daytona, Blaxel, Islo, Gensee, NVIDIA OpenShell, and Boxlite for cloud sandbox hosts.

The hosted-platform comparison below covers Databricks, Modal, Daytona, Blaxel, and Islo. OpenShell connects to your selected gateway; Boxlite can use a local micro-VM runtime or a remote boxlite serve pool. Gensee and Databricks are managed-host providers only: their control planes start the host over HTTPS, so they support the server-managed flow but not the CLI bootstrap commands. Databricks sandboxes are driven through the Databricks Sandbox SDK.

For local microVMs, use Microsandbox. Its VMs run on the machine running the server or CLI, so they depend on that machine staying awake.

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[databricks]'  # for Databricks Sandbox
pip install 'omnigent[modal]'       # for Modal
pip install 'omnigent[daytona]'     # for Daytona
pip install 'omnigent[blaxel]'      # for Blaxel
pip install 'omnigent[islo]'        # for Islo
pip install 'omnigent[openshell]'   # for OpenShell
pip install 'omnigent[boxlite]'     # for Boxlite
pip install 'omnigent[microsandbox]' # for local microVMs

Gensee needs no extra: it talks to the Gensee control plane over HTTPS and installs no provider SDK in Omnigent.

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

Databricks: Sandboxes run as each user's own Databricks account, so there is no shared provider key on the server. Each user connects under Settings → Connections → Databricks, which needs an account-level custom OAuth app integration configured on the server; see Databricks settings.

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_…

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

OpenShell: select a gateway with openshell gateway select <name>, or set OPENSHELL_GATEWAY on the server. The launcher uses that gateway connection and does not require a separate API key.

Gensee: set the API token variable named by sandbox.gensee.api_token_env (GENSEE_CONTROLLER_API_TOKEN by default) on the server. Gensee currently provisions endpoints and tokens for contracted organizations; keep the token in the server process environment, not in config.yaml.

export GENSEE_CONTROLLER_API_TOKEN=…

Boxlite: local mode requires KVM on Linux and no provider credential. For a remote boxlite serve pool, set BOXLITE_API_KEY on the server and configure the pool endpoint in the Boxlite settings.

Microsandbox: no provider credentials or daemon are needed; the install extra includes the runtime. Use Apple Silicon macOS or glibc Linux with access to /dev/kvm (typically through the kvm group). Intel Macs are not supported.

Provider control credentials stay on the launching process and never enter the sandbox. Web users log in to Omnigent, not the sandbox provider.

3. Configure a provider

Add a sandbox section to your server config YAML (~/.omnigent/config.yaml on a laptop, /data/config.yaml in Docker). A typical Modal configuration looks like this:

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

See common settings for the top-level fields, Modal settings for the provider block, and host configuration for host_config. The full cloud sandbox configuration reference also covers the other providers and lifecycle settings.

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.

Optionally point the sandbox at a git repository to clone. Use the composer's Repository control to pick a repo from your connected GitHub account or paste a clone URL, and pin a branch; leave it empty for a bare sandbox with a server-created workspace. The repo is cloned inside the sandbox and becomes the session's working directory. Admins can make these clones faster with the optional sandbox.git_clone block, which limits history depth, branch selection, and blob fetching for fresh checkouts on providers that support it.

Some providers can clone several repositories into one sandbox. When the selected provider supports it, keep adding entries in the Repository control (up to 10 repos). Omnigent clones them in parallel as siblings under the sandbox workspace: with a single repo the agent starts inside it, and with several the agent starts in the parent directory that holds them all. Two repos that would land in the same directory name (for example org-a/api and org-b/api) are disambiguated by owner. Multi-repo is a per-provider capability — the Kubernetes managed sandbox supports it, while single-repo providers accept only one repo and reject a request for several. The picker adapts to the selected provider, so it offers the multi-repo list only when that provider supports it.

Calling the REST API directly, pass a single repository in workspace or several in workspaces (a list of clone URLs, each optionally #<branch>) on POST /v1/sessions. The two are mutually exclusive, workspaces requires a managed session (host_type: "managed"), and it takes at most 10 repositories.

5. Run automations in sandboxes (optional)

Scheduled tasks can use the same launch path: create a task with execution_target: managed_sandbox (or pick New Sandbox in the automation dialog's host picker) and each firing provisions a fresh sandbox with a clean workspace. Existing managed sandbox hosts cannot be pinned as an automation's host, and the option is only offered when this server has a managed sandbox provider configured.

An automation's sandbox follows the server's sandbox configuration exactly like one launched for a chat — the automation does not override timeouts or terminate the sandbox when a run finishes. Choose provider lifetime, idle, and cleanup settings (including the reaper below) that fit your automation frequency and resource budget; enabling managed sandboxes alone does not guarantee a short shutdown time.

CLI

Create and manage cloud sandbox hosts from the command line. The commands are the same across CLI-capable providers; switch the --provider flag:

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

Databricks, Boxlite, and Gensee support the server-managed flow but not these CLI bootstrap commands.

For Microsandbox, use --provider microsandbox and pass a --server URL reachable from the VM; see Microsandbox settings.

For a Blaxel CLI launch, list any credentials the host or agent needs in OMNIGENT_BLAXEL_SANDBOX_ENV 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 the provider's CLI or console when you no longer need it.

Reap stale sandboxes (optional)

By default a managed sandbox lives until its session is deleted (or the provider's own lifetime cap reaps it). To automatically terminate sandboxes whose hosts have gone offline and stayed offline, add an optional reaper block to sandbox:. It is deployment-wide — configure it next to provider (or providers:), never inside an individual provider entry:

sandbox:
  provider: modal
  server_url: https://your-server.example.com
  reaper:                              # optional; disabled by default
    enabled: true                      # default: false
    terminate_after_offline_days: 30   # default: 30 days
    sweep_interval_s: 86400            # default: 1 day

• enabled — whether the server starts the reaper loop. Defaults to false because terminating user compute is destructive; opt in explicitly.
• terminate_after_offline_days — the minimum number of days since a managed host's last heartbeat before its current sandbox generation may be terminated. Defaults to 30.
• sweep_interval_s — seconds between complete sweeps. Defaults to 86400 (one day).

Both terminate_after_offline_days and sweep_interval_s must be positive integers. Setting reaper inside a providers: list entry is rejected at startup — one loop covers the whole deployment and dispatches each termination through the provider recorded on the managed host it is reaping.

Reaping detaches only the stale sandbox generation: the session transcript and the durable host binding stay, so the next message to that session can launch a fresh sandbox under the same host identity. A provider termination that fails stays pending and is retried on a later sweep.

Community sandbox providers

The providers above ship with Omnigent. Beyond them, the server discovers additional sandbox providers at startup through a plugin registry, so a new hosting platform can be added as a separate package without changing the core omnigent package.

An installed provider's name is accepted in sandbox.provider, and its provider-specific block is validated at server startup when it declares a config model. Configured community providers are offered as managed-launch options in the web UI, so they must implement that lifecycle. Install the plugin in the server's Python environment and restart to discover it. A missing or rejected plugin makes its provider name invalid in server configuration.

Configure a contributed provider

Set sandbox.provider to the contributed name and, if the provider declares a config model, add a matching sandbox.<provider> block:

sandbox:
  provider: acme
  server_url: https://your-server.example.com
  acme:
    namespace: sandboxes

The block is validated against the provider's declared config model when the server starts. Whether unknown keys are rejected depends on that model. A provider that declares no config model receives no provider-specific config arguments.

Build a provider plugin

Follow Community Sandbox Providers for the implementation guide: choose an exec-model or provider-controlled launcher, define validated configuration, register the package entry point, and test managed startup and cleanup. The guide also covers optional CLI bootstrap, resume, and multi-repository support.