wehub-resource-sync
492 lines
24 KiB
Markdown
492 lines
24 KiB
Markdown
# Omnigent on Islo
|
|
|
|
[Islo](https://islo.dev) sandboxes give you disposable cloud machines for
|
|
running Omnigent hosts, two ways:
|
|
|
|
- **CLI-launched**: `omnigent sandbox create` / `connect` provisions a
|
|
sandbox from your terminal, ships your local checkout into it, and
|
|
registers it as a host with your server.
|
|
- **Server-managed**: the server provisions a sandbox automatically when
|
|
a session is created with `"host_type": "managed"` and terminates it
|
|
when the session is deleted.
|
|
|
|
Sandboxes boot from the official prebaked host image, so startup is
|
|
seconds. Unlike Modal and Daytona, the Islo launcher talks to the Islo
|
|
HTTP API directly through `httpx` (already an Omnigent dependency), so
|
|
there is **no provider SDK extra to install** — just an API key.
|
|
|
|
What makes Islo different from the other providers, and shapes the rest
|
|
of this guide:
|
|
|
|
- **A credential gateway.** Islo can inject LLM/API keys into a sandbox's
|
|
outbound traffic at the network layer, so the raw key never reaches the
|
|
sandbox process. This is a first-class, recommended path for model
|
|
credentials (see [Model credentials](#model-credentials-llm-keys)) and
|
|
has no equivalent on Modal or Daytona.
|
|
- **No local port forward.** Islo can't forward a sandbox→laptop callback
|
|
port, so the interactive in-sandbox `omnigent login` / App OAuth step is
|
|
skipped automatically (as on Modal and Daytona).
|
|
- **No lifetime cap.** Islo sandboxes run until deleted (like Daytona,
|
|
unlike Modal's 24 h).
|
|
|
|
## Prerequisites
|
|
|
|
Install the [Islo CLI](https://docs.islo.dev) and create an API key, then
|
|
make it available where the launcher runs — your shell for the CLI flow,
|
|
the **server** process for managed sandboxes:
|
|
|
|
```bash
|
|
curl -fsSL https://islo.dev/install.sh | sh # install the islo CLI
|
|
islo login # browser OAuth (one-time)
|
|
islo api-key create omnigent --show # prints an islo_key_… value
|
|
export ISLO_API_KEY=islo_key_…
|
|
# Optional: a non-default API endpoint
|
|
# export ISLO_BASE_URL=https://api.islo.dev
|
|
```
|
|
|
|
`ISLO_API_KEY` is exchanged for a short-lived session token at
|
|
`POST /auth/token`; the token is cached until shortly before expiry. The
|
|
key is the only required credential — no SDK, no `~/.config` file.
|
|
|
|
> [!NOTE]
|
|
> **Islo cannot forward a local callback port into the sandbox.** The
|
|
> interactive `omnigent login` browser flow (and the in-sandbox App OAuth
|
|
> callback) needs a sandbox→laptop port forward, which Islo doesn't
|
|
> provide — so the CLI skips that step automatically, exactly as it does
|
|
> for Modal and Daytona. For a server that requires authentication, inject
|
|
> the credentials instead (see
|
|
> [Connecting to an authenticated server](#connecting-to-an-authenticated-server)).
|
|
|
|
## The host image
|
|
|
|
Sandboxes boot from `ghcr.io/omnigent-ai/omnigent-host:latest`, published
|
|
by CI from the `host` target of
|
|
[`deploy/docker/Dockerfile`](../docker/Dockerfile) with Omnigent and its
|
|
dependencies preinstalled — including the coding-harness CLIs (`claude`,
|
|
`codex`, `pi`, `kiro-cli`), so agents on any harness run without an in-sandbox
|
|
install.
|
|
|
|
To use a different image (a fork, or extra tooling baked in), build the
|
|
same target and push it anywhere Islo can pull from:
|
|
|
|
```bash
|
|
docker build -f deploy/docker/Dockerfile --target host \
|
|
--platform linux/amd64 \
|
|
-t docker.io/<you>/omnigent-host:latest .
|
|
docker push docker.io/<you>/omnigent-host:latest
|
|
```
|
|
|
|
Then point Omnigent at it — `OMNIGENT_ISLO_HOST_IMAGE` for the CLI flow,
|
|
or `sandbox.islo.image` in the server config for the managed flow. For a
|
|
private registry, configure the pull credentials on the Islo side (Islo
|
|
pulls the image, not Omnigent).
|
|
|
|
> [!IMPORTANT]
|
|
> **Native terminals need `bubblewrap`.** The `claude-native` /
|
|
> `codex-native` / `kiro-native` / `pi` harnesses wrap each agent terminal in a bubblewrap
|
|
> (`bwrap`) OS-sandbox, and on Linux that isolation is mandatory and
|
|
> fail-loud — a host image without the `bwrap` binary makes those terminals
|
|
> fail to start (`linux_bwrap sandbox requires the 'bwrap' binary on PATH`).
|
|
> The `host` Dockerfile target installs `bubblewrap`; if you bring your own
|
|
> image, install it there too. See [Troubleshooting](#troubleshooting).
|
|
|
|
## CLI-launched sandboxes
|
|
|
|
Provision a sandbox and ship your local checkout into it:
|
|
|
|
```bash
|
|
omnigent sandbox create --provider islo
|
|
```
|
|
|
|
This pulls the host image, builds wheels from your local checkout, and
|
|
overlays them on top — so the sandbox runs *your* code, not whatever the
|
|
image was built from. Then register it as a host with your server:
|
|
|
|
```bash
|
|
omnigent sandbox connect --provider islo \
|
|
--sandbox-id <id-printed-by-create> \
|
|
--server https://your-host
|
|
```
|
|
|
|
`connect` runs `omnigent host` inside the sandbox and holds the
|
|
connection open in your terminal — Ctrl-C tears it down. New sessions
|
|
targeting that host now run in the sandbox.
|
|
|
|
Running multiple sandboxes against one server? Pass a unique
|
|
`--host-name <label>` to each `connect` — the server keys hosts on
|
|
(owner, name), and sandboxes that share a hostname collide.
|
|
|
|
Sandboxes are disposable. When your code changes, create a new one — and
|
|
delete the old one (Islo sandboxes have no lifetime cap, so an abandoned
|
|
sandbox keeps billing until removed via `islo rm <id>` or the
|
|
[dashboard](https://app.islo.dev)).
|
|
|
|
To inject LLM/git credentials into a CLI-launched sandbox, set
|
|
`OMNIGENT_ISLO_SANDBOX_ENV` in your shell to a comma-separated list of
|
|
variable names (e.g. `ANTHROPIC_API_KEY,GIT_TOKEN`) before running
|
|
`create` — the named variables are copied from your environment into the
|
|
sandbox at provision time. A listed name that is **not** set fails the
|
|
launch loudly (it would otherwise surface much later as an opaque harness
|
|
auth failure inside the sandbox).
|
|
|
|
### Connecting to an authenticated server
|
|
|
|
`connect` runs `omnigent host` inside the sandbox, and that host must
|
|
present credentials when it dials back to a server that requires
|
|
authentication. The interactive `omnigent login` browser flow can't run
|
|
inside an Islo sandbox (no callback port forward), so inject the keys for
|
|
the relevant server instead — name them in `OMNIGENT_ISLO_SANDBOX_ENV`
|
|
before `create`:
|
|
|
|
```bash
|
|
export OMNIGENT_ISLO_SANDBOX_ENV=DATABRICKS_HOST,DATABRICKS_TOKEN
|
|
omnigent sandbox create --provider islo
|
|
```
|
|
|
|
The in-sandbox host mints a fresh bearer token from those credentials on
|
|
every connect and reconnect. For a Databricks-fronted server, inject
|
|
`DATABRICKS_HOST` plus either `DATABRICKS_TOKEN` (a PAT) or
|
|
`DATABRICKS_CLIENT_ID` / `DATABRICKS_CLIENT_SECRET` (an OAuth service
|
|
principal — re-minting keeps a long-lived sandbox connected past any
|
|
single token's expiry).
|
|
|
|
A server with no authentication on the host tunnel needs none of this,
|
|
and neither do [server-managed sandboxes](#server-managed-sandboxes) —
|
|
those authenticate with a server-minted per-launch token automatically.
|
|
|
|
## Server-managed sandboxes
|
|
|
|
Add a `sandbox:` section to the server config (`omnigent server -c
|
|
config.yaml`, or `<data_dir>/config.yaml`):
|
|
|
|
```yaml
|
|
sandbox:
|
|
provider: islo
|
|
server_url: https://your-host # public URL sandboxes dial back to
|
|
```
|
|
|
|
`server_url` must be reachable *from Islo's cloud* — a public HTTPS URL,
|
|
not `localhost`. The server itself needs `ISLO_API_KEY` (and optional
|
|
`ISLO_BASE_URL`) in its environment. Sessions created with
|
|
`host_type: "managed"` (the API call or the Web UI's New Sandbox option)
|
|
then run on a fresh Islo sandbox; the create returns immediately and
|
|
provisioning happens in the background, exactly like the [Modal managed
|
|
flow](../modal/README.md#server-managed-sandboxes) — including repository
|
|
workspaces, the first-message rendezvous, and dead-sandbox relaunch.
|
|
|
|
```bash
|
|
curl -X POST https://your-host/v1/sessions \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"agent_id": "agent_...", "host_type": "managed"}'
|
|
```
|
|
|
|
Each managed sandbox authenticates back with a server-minted, per-launch
|
|
token (7-day TTL — see [Lifecycle](#lifecycle-notes)); no user
|
|
credentials enter the sandbox for the server connection.
|
|
|
|
### Managed hosts and server auth
|
|
|
|
How the dial-back authenticates depends on how the **server** does auth,
|
|
and there is one interaction worth knowing before you deploy. A managed
|
|
sandbox opens two kinds of connections back to the server:
|
|
|
|
- the **host tunnel** (`/v1/hosts/<id>/tunnel`), which the per-launch
|
|
token authenticates directly — the server mints it, scopes it to one
|
|
host, and resolves the owner from it. This always works.
|
|
- one **runner tunnel** per session (`/v1/runners/<token>/tunnel`), opened
|
|
by the runner subprocess the host spawns. The runner authenticates with
|
|
*whatever server credential it can resolve* — a proxy-injected identity
|
|
(header / OIDC), or a stored `omnigent login` token (local hosts only; a
|
|
fresh managed sandbox has none) — **not** the per-launch host token.
|
|
|
|
The consequence:
|
|
|
|
- **Header / OIDC-proxy auth, or single-user (no-auth) servers** — the
|
|
runner tunnel needs no extra identity, so managed hosts work out of the
|
|
box. **Verified end-to-end on a single-user server**: a session created
|
|
with `host_type: "managed"` provisioned an Islo sandbox from the bwrap
|
|
image, the launcher cleared the seeded `apiKeyHelper`, the host *and*
|
|
runner tunnels connected, and a native Claude terminal ran on the
|
|
injected `CLAUDE_CODE_OAUTH_TOKEN` subscription.
|
|
- **The built-in `accounts` provider (`OMNIGENT_AUTH_ENABLED=1`)** — the
|
|
runner tunnel additionally requires a *user* identity, which the
|
|
per-launch host token does not carry, so the runner dial-back is refused
|
|
(`403`) even though the host tunnel connects. This is a framework-level
|
|
managed-host interaction shared by **all** sandbox providers (Modal /
|
|
Daytona / Islo), not specific to Islo.
|
|
|
|
So for a managed Islo deployment, front the server with **header or OIDC
|
|
auth** (a reverse proxy / IdP injects the user identity on every request,
|
|
including the runner WebSocket — see
|
|
[`deploy/README.md#auth`](../README.md#auth)), or run it single-user. The
|
|
`accounts` provider is fine for CLI-launched hosts (you `omnigent login`,
|
|
and that token is what the in-sandbox host forwards), but not yet for the
|
|
managed runner dial-back.
|
|
|
|
Optional `islo:` settings:
|
|
|
|
```yaml
|
|
sandbox:
|
|
provider: islo
|
|
server_url: https://your-host
|
|
islo:
|
|
image: docker.io/<you>/omnigent-host:latest # default: official image
|
|
env: [OPENAI_API_KEY, GIT_TOKEN] # copy from server env
|
|
base_url: https://api.islo.dev # non-default API endpoint
|
|
gateway_profile: default # Islo gateway for egress + credential injection
|
|
snapshot_name: warm-host # boot from a prebaked snapshot
|
|
workdir: /root/workspace # sandbox working directory
|
|
vcpus: 2
|
|
memory_mb: 4096
|
|
disk_gb: 20
|
|
```
|
|
|
|
## Model credentials (LLM keys)
|
|
|
|
A fresh sandbox has no model credentials of your own. Islo offers **two
|
|
distinct ways** to give the agent a model — and they interact, so pick one
|
|
deliberately per harness.
|
|
|
|
### Option A — Islo gateway integration (recommended)
|
|
|
|
This is the Islo-native path with no Modal/Daytona equivalent. Islo
|
|
[gateways](https://docs.islo.dev/cli/gateways) "automatically attach API
|
|
keys, tokens, and secrets to outbound requests" at the **network layer** —
|
|
*"credentials never reach the sandbox process."* You connect a provider
|
|
once, server-side, and every sandbox picks it up:
|
|
|
|
```bash
|
|
islo login --tool claude # OAuth-connect Anthropic (alias: --tool anthropic)
|
|
islo login --tool openai # …and/or OpenAI
|
|
islo status # shows connected integrations
|
|
```
|
|
|
|
This is **not Claude-specific** — it's how Islo supplies model
|
|
credentials to *every* harness. Islo pre-seeds each sandbox with a
|
|
**phantom** placeholder key (`islo_phantom_…`) in whatever location the
|
|
harness reads, per provider:
|
|
|
|
| Harness | Phantom key location | Provider endpoint |
|
|
|---|---|---|
|
|
| Claude Code (`claude-native`, `claude-sdk`, `pi`) | `apiKeyHelper` in `~/.claude/settings.json` | `api.anthropic.com` |
|
|
| Codex / OpenAI agents | `OPENAI_API_KEY` env var | `api.openai.com` |
|
|
|
|
The harness sends that placeholder to its provider endpoint; the gateway
|
|
intercepts the request and swaps it for your connected credential before
|
|
forwarding. The raw key never lands in the sandbox, and the connection is
|
|
team-wide — other members don't need their own. (We observed both phantom
|
|
keys pre-seeded in a single sandbox.)
|
|
|
|
These integrations connect **provider API keys** (per-token billing), not
|
|
plan/subscription auth — `--tool claude` gives an Anthropic API key, not a
|
|
Claude Pro/Max subscription; `--tool openai` gives an OpenAI API key, not
|
|
a ChatGPT plan. To use a subscription or plan token on any harness (a
|
|
Claude Pro/Max token, a Codex access token), use
|
|
[Option B](#option-b--omnigent-env-injection-your-own-key-or-a-subscription).
|
|
|
|
> [!IMPORTANT]
|
|
> If `islo status` shows **"No integrations connected"** for a provider,
|
|
> its phantom key resolves to nothing — the harness falls back to a failing
|
|
> request (Claude reports "API Usage Billing" and retries). Connect the
|
|
> integration for each provider whose harness you use.
|
|
|
|
#### Path A under managed hosts
|
|
|
|
This is where the gateway shines: when the **server** launches sandboxes,
|
|
you configure **no model credential on the Omnigent side at all**. The
|
|
flow:
|
|
|
|
```
|
|
admin (once): islo login --tool claude → connects Anthropic to the Islo ACCOUNT
|
|
│
|
|
server ──ISLO_API_KEY──▶ Islo API "create sandbox" ──▶ sandbox under that account
|
|
│ Islo pre-seeds the
|
|
│ phantom apiKeyHelper
|
|
▼
|
|
agent's claude → api.anthropic.com (phantom key) ──▶ Islo gateway swaps in the real key
|
|
```
|
|
|
|
The Omnigent server only ever holds `ISLO_API_KEY` — the credential it
|
|
uses to *create* sandboxes. Because every managed sandbox is created under
|
|
that Islo account, and integrations are connected at the **account/team**
|
|
level, each one inherits the connected Claude credential through the
|
|
gateway automatically. The only Omnigent-side knob is which gateway a
|
|
managed sandbox uses:
|
|
|
|
```yaml
|
|
sandbox:
|
|
provider: islo
|
|
server_url: https://your-host
|
|
islo:
|
|
gateway_profile: default # the Islo gateway carrying the connected integration
|
|
```
|
|
|
|
Two consequences worth internalizing:
|
|
|
|
- **No model secret lives in the Omnigent server's config or
|
|
environment** — nothing to leak there. Contrast [Option B under managed
|
|
hosts](#option-b--omnigent-env-injection-your-own-key-or-a-subscription),
|
|
where the key sits in `sandbox.islo.env` (copied from the server's env
|
|
into each sandbox).
|
|
- **The integration must be connected on the same Islo account the
|
|
server's `ISLO_API_KEY` belongs to.** If your server runs under a
|
|
dedicated service/CI Islo account, run `islo login --tool claude` while
|
|
authenticated as *that* account — not a personal laptop login.
|
|
|
|
### Option B — Omnigent env injection (your own key or a subscription)
|
|
|
|
Bring your own credential by naming it in `OMNIGENT_ISLO_SANDBOX_ENV`
|
|
(CLI) or `sandbox.islo.env` (managed); the launcher copies the value from
|
|
the launching environment into the sandbox, and the in-sandbox host
|
|
forwards the standard harness credential vars to its runners:
|
|
|
|
| Variable | Enables |
|
|
|---|---|
|
|
| `ANTHROPIC_API_KEY` | Claude models on the Anthropic API |
|
|
| `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` | Anthropic-compatible gateways (LiteLLM, Bedrock/Vertex bridges, corporate proxies) |
|
|
| `CLAUDE_CODE_OAUTH_TOKEN` | claude-code with a Claude **subscription** (no API key) |
|
|
| `OPENAI_API_KEY` / `OPENAI_BASE_URL` | OpenAI or any OpenAI-compatible endpoint (OpenRouter, vLLM, Ollama, …) |
|
|
| `CODEX_ACCESS_TOKEN` | codex with a ChatGPT Business/Enterprise workspace |
|
|
| `GEMINI_API_KEY` | Gemini on the Google AI API |
|
|
|
|
The full per-plan recipes (subscriptions, gateways, open-source models)
|
|
are identical to Modal — see the [variable table and
|
|
recipes](../modal/README.md#llm-credentials-for-managed-sandboxes). For a
|
|
Claude **subscription** specifically, run `claude setup-token` on your own
|
|
machine (one-time browser auth) and inject the resulting long-lived token
|
|
as `CLAUDE_CODE_OAUTH_TOKEN`. For env vars beyond the standard set, inject
|
|
`OMNIGENT_RUNNER_ENV_PASSTHROUGH=NAME1,NAME2`.
|
|
|
|
> [!NOTE]
|
|
> **Your injected Claude credential automatically wins over Islo's phantom
|
|
> helper.** Islo seeds an `apiKeyHelper` into every sandbox, and Claude Code
|
|
> would normally prefer it over a `CLAUDE_CODE_OAUTH_TOKEN`/`ANTHROPIC_API_KEY`
|
|
> in the environment. So when you inject one of those, the Islo launcher
|
|
> strips the seeded `apiKeyHelper` at provision time — for **both**
|
|
> CLI-launched and server-managed sandboxes — leaving your credential as the
|
|
> sole auth path. No manual step, nothing to run inside the sandbox.
|
|
|
|
Codex/OpenAI needs nothing special either — its phantom is the
|
|
`OPENAI_API_KEY` env var, which your injected `OPENAI_API_KEY` simply
|
|
overrides.
|
|
|
|
### Choosing between A and B
|
|
|
|
| | Option A — gateway | Option B — env injection |
|
|
|---|---|---|
|
|
| Credential | provider **API key** (Anthropic, OpenAI, …) | your API key **or** subscription/plan token |
|
|
| Billing | per-token API | API key, or your subscription/plan |
|
|
| Key in sandbox? | **No** (gateway injects out-of-band) | Yes (in the sandbox env) |
|
|
| Scope | account/team-wide, all sandboxes | per-sandbox |
|
|
| Managed-host config | just `gateway_profile`; no secret on server | key in `sandbox.islo.env` |
|
|
| Best for | **managed / production**, API-key billing | your own **subscription** or key; CLI or managed |
|
|
| Catch | needs a connected integration | the injected var must be set where the launcher runs |
|
|
|
|
Pick **one per harness** — connect Islo's integration *or* inject your own
|
|
credential, never both. Both work in either launch flow: the launcher
|
|
strips Islo's seeded `apiKeyHelper` automatically when you inject a Claude
|
|
credential. The same two patterns apply to Codex/OpenAI (`islo login --tool
|
|
openai`, or inject `OPENAI_API_KEY` / `CODEX_ACCESS_TOKEN`).
|
|
|
|
### Git credentials (private repositories)
|
|
|
|
Inject an HTTPS token as `GIT_TOKEN` (GitLab: add `GIT_USERNAME=oauth2`)
|
|
via `OMNIGENT_ISLO_SANDBOX_ENV` / `sandbox.islo.env`. The host image's git
|
|
credential helper answers HTTPS auth from it for both the launch-time
|
|
clone and the agent's later `fetch` / `push`, writing nothing to disk. Use
|
|
HTTPS repository URLs. Details by provider match the [Modal git
|
|
guide](../modal/README.md#git-credentials-private-repositories).
|
|
|
|
## Security considerations
|
|
|
|
- **Path A keeps the model key out of the sandbox — a real advantage.**
|
|
With the gateway, the agent process only ever sees the phantom
|
|
placeholder; the real key is injected at Islo's network edge. A
|
|
prompt-injected or compromised agent can't exfiltrate a key it never
|
|
holds. This is the strongest credential posture of the three providers
|
|
for model keys, and the reason to prefer Option A where API-key billing
|
|
is acceptable.
|
|
- **The gateway terminates TLS to inject.** Credential injection means
|
|
Islo's gateway sits in the path of the agent's outbound LLM traffic and
|
|
re-originates it — so that traffic (prompts, completions, tool output
|
|
sent to the model) is visible at Islo's edge. Acceptable for most teams,
|
|
but weigh it for highly sensitive workloads, and scope the
|
|
`gateway_profile` to exactly the egress you intend.
|
|
- **Option B puts the key in the sandbox.** A subscription token or API key
|
|
named in `sandbox.islo.env` is copied into the sandbox environment at
|
|
provision time and lives there for the sandbox's life. Prefer scoped,
|
|
short-lived credentials, and rely on the per-terminal `bwrap` sandbox
|
|
(below) to keep the agent away from it.
|
|
- **The agent terminal is sandboxed away from those secrets.** Native
|
|
harness terminals run under a bubblewrap OS-sandbox that masks dotfiles
|
|
(`~/.ssh`, `~/.aws`, the injected `~/.omnigent` server token) and pins
|
|
the agent to its workspace — defense-in-depth *inside* the Islo sandbox,
|
|
independent of Islo's own isolation. This is why the image must ship
|
|
`bwrap` (see [the host image](#the-host-image)).
|
|
- **All managed sandboxes share one Islo org + `ISLO_API_KEY`.**
|
|
Cross-user isolation rides on Islo's sandbox boundaries, and the shared
|
|
org key can enumerate and delete any sandbox — the same single-tenant-org
|
|
shape as the Modal and Daytona providers. Scope the org to this workload.
|
|
- **The launch token's lifetime is 7 days.** Islo sandboxes have no
|
|
platform lifetime cap, so the per-launch host token must outlive a
|
|
long-running sandbox across reconnects (a longer replay window than
|
|
Modal's ~24 h; same as Daytona). A relaunch mints a fresh one.
|
|
|
|
## Lifecycle notes
|
|
|
|
- **No platform lifetime cap.** Unlike Modal's 24-hour limit, Islo
|
|
sandboxes run until deleted. The managed flow deletes a sandbox when its
|
|
session is deleted, and the dead-sandbox relaunch path replaces one that
|
|
crashed or was removed out-of-band. CLI-launched sandboxes you delete
|
|
yourself (`islo rm <id>`).
|
|
- **Resources.** Sandboxes default to 2 vCPUs and 4 GiB of memory;
|
|
override per managed launch with `vcpus` / `memory_mb` / `disk_gb`.
|
|
- **Warm starts.** Set `sandbox.islo.snapshot_name` to boot from a
|
|
prebaked Islo snapshot instead of a cold image pull.
|
|
- **Provider-side lifecycle** (list / status / delete / stop) — use the
|
|
`islo` CLI (`islo ls`, `islo rm <id>`) or the
|
|
[dashboard](https://app.islo.dev) directly.
|
|
|
|
## Cost
|
|
|
|
Islo bills usage with no seat licenses or idle fees: ~$0.07/CPU-hour,
|
|
~$0.04/GB-hour of memory, ~$0.0007/GB-hour of disk — about $0.25/hour for
|
|
the default 2 vCPU / 4 GiB sandbox while it runs. New accounts get $50 of
|
|
free credits. Rates: [islo.dev](https://islo.dev).
|
|
|
|
## Troubleshooting
|
|
|
|
- **Native Claude/Codex terminal fails with `linux_bwrap sandbox requires
|
|
the 'bwrap' binary on PATH`.** The native harnesses wrap each agent
|
|
terminal in a bubblewrap OS-sandbox; the host image must ship
|
|
`bubblewrap`. The `host` Dockerfile target installs it — rebuild from a
|
|
current image, or for a one-off on a CLI-launched sandbox run
|
|
`apt-get install -y bubblewrap` inside it.
|
|
- **Claude shows "API Usage Billing" / "both `CLAUDE_CODE_OAUTH_TOKEN` and
|
|
`apiKeyHelper` set."** You injected your own Claude credential (Option B)
|
|
but Islo's phantom `apiKeyHelper` is still present — the launcher strips it
|
|
automatically at provision, so this means the strip didn't run: confirm the
|
|
credential is named in `OMNIGENT_ISLO_SANDBOX_ENV` / `sandbox.islo.env` (the
|
|
signal the launcher keys on), and check the provision log for the
|
|
"clearing Islo's seeded apiKeyHelper" line.
|
|
- **Requests retry then fail with no obvious error.** `islo status` shows
|
|
no connected integration, so the phantom `apiKeyHelper` resolves to
|
|
nothing. Connect one (Option A) or switch to Option B.
|
|
- **"managed host did not come online within 120s."** Check that
|
|
`server_url` is publicly reachable from Islo's cloud, then inspect the
|
|
in-sandbox host log: `~/.omnigent/logs/host-runner/*.log`.
|
|
- **Agent has no credentials.** Verify the injected var names match the
|
|
forwarded set above (or are named in `OMNIGENT_RUNNER_ENV_PASSTHROUGH`),
|
|
and that each name was actually set in the launching environment.
|
|
|
|
## Environment variable reference
|
|
|
|
| Variable | Where it's read | Purpose |
|
|
|---|---|---|
|
|
| `ISLO_API_KEY` | CLI machine / server | Islo API credentials (required) |
|
|
| `ISLO_BASE_URL` | CLI machine / server | Non-default Islo API endpoint (default `https://api.islo.dev`) |
|
|
| `OMNIGENT_ISLO_HOST_IMAGE` | CLI machine / server | Override the host image ref (`sandbox.islo.image` takes precedence for managed) |
|
|
| `OMNIGENT_ISLO_SANDBOX_ENV` | CLI machine / server | Comma-separated launcher-side env var names to inject (`sandbox.islo.env` takes precedence for managed) |
|
|
| `OMNIGENT_RUNNER_ENV_PASSTHROUGH` | inside the sandbox (injected) | Extra env var names the host forwards to runners |
|
|
| `GIT_TOKEN` / `GIT_USERNAME` | inside the sandbox (injected) | HTTPS credentials for private repository clone / fetch / push |
|