Running ox in constrained environments

"Ephemeral" is not a mode. It's a label for a constellation of capabilities the sandbox provides or withholds. Claude Code Cloud, Devin, GitHub Actions, and Codespaces are not all the same shape — one has persistent disk and an 8-hour lifetime, one writes disk to a snapshot but can run a daemon, one is gone in five minutes. ox probes each capability once at startup and lets every subsystem ask for what it actually needs.

This page covers the capability model, what works and what doesn't, how to set ox up on each major platform, and the exact error strings runbooks should grep for.

The capability model

When ox starts, it probes the environment for four capabilities and a lifetime hint:

Subsystems consult capabilities directly. The local CodeDB indexer only runs when PersistDisk && LongLivedHelper. ox login's browser flow only attempts to launch when Browser is true; otherwise it refuses with a clear "set SAGEOX_TOKEN" message. Session staging picks ~/.sageox/sessions/... when PersistDisk is true, otherwise $TMPDIR/ox-sessions/....

Capability matrix per platform

Override knobs

You can override the probe at the capability level:

Use the capability-level overrides when the auto-probe gets it wrong (e.g. a brand-new sandbox ox doesn't recognize). Use OX_EPHEMERAL=1 when you just want "treat me as fully constrained" without spelling out each axis.

Prerequisites

• A Personal Access Token exported as SAGEOX_TOKEN.
• A static ox binary on PATH. The install script at https://install.sageox.ai/ox ships a single self-contained Go binary with no runtime dependencies.

What works, what doesn't

Subcommand behavior in constrained environments. "Designed-for" subcommands are the supported entrypoints; "degraded" still works but with a noted trade-off; "refused" exits non-zero with a clear pointer.

Session uploads are idempotent on (agent_id, session_id). Retrying a failed upload is safe — the second call is a no-op if the first actually succeeded.

Error contract

These strings are part of the CLI's contract surface. Operator runbooks grep for them; they will not be reworded without a deprecation pass.

Exit codes follow sysexits.h: usage errors are 64, auth failures are 77.

Claude Code Cloud

Anthropic's Managed Agents run Claude Code in an isolated sandbox defined by an environment YAML.

Environment file

# .claude/environment.yml
packages:
  go: ["github.com/sageox/ox/cmd/ox@latest"]

secrets:
  SAGEOX_TOKEN: oxp_...    # paste your PAT here, or reference a secret

hooks:
  SessionStart: |
    ox agent prime

• packages.go installs ox from source into the sandbox image. Pin to a specific version (@v0.42.0) for reproducibility once you have one you like.
• secrets.SAGEOX_TOKEN is injected at runtime — it does not appear in the image layer. Prefer Anthropic's Secrets dashboard over inlining the value.
• hooks.SessionStart runs at the start of every Claude session. ox auto-detects the constrained environment from CLAUDE_CODE_REMOTE and configures itself accordingly — no OX_EPHEMERAL export needed.

Networking

Claude Code Cloud defaults to limited egress. Add the SageOx hosts to your allowed_hosts:

network:
  mode: limited
  allowed_hosts:
    - api.sageox.ai
    - install.sageox.ai
    - <your-team-context-git-host>   # gitlab.com, github.com, etc.

If you forget the team-context git host, ox agent prime will fail with a clone error pointing at the missing domain. Add it and retry.

Verify

Start a Claude session and look for these lines in the SessionStart log:

ox agent prime: constrained environment (CLAUDE_CODE_REMOTE)
ox agent prime: authenticated as <your-email>
ox agent prime: team context loaded (<N> files)

If you see SAGEOX_TOKEN expired or invalid, rotate the PAT — see Personal Access Tokens.

Devin

Cognition's Devin repo setup splits configuration into three sections: setup (bakes into the snapshot), startup (runs every session), and secrets.

Setup commands

One-time, runs when Devin builds the workspace snapshot:

curl -fsSL https://install.sageox.ai/ox | sh
ox --version    # sanity check that install succeeded

Startup commands

Runs at the start of every Devin session, on top of the snapshot:

ox agent prime

ox auto-detects the Devin sandbox from DEVIN_TASK_ID and configures itself accordingly.

Secrets

In the Devin Secrets dashboard, add:

SAGEOX_TOKEN=oxp_...

Devin injects this into the environment before startup commands run. Never paste the token into the startup-commands box — that value is logged.

Notes

• Devin keeps the snapshot warm across sessions, so ox agent prime runs against a pre-installed binary. If you bump ox, re-run the setup commands or invalidate the snapshot.

GitHub Actions

For CI use cases — generating release notes, distilling sessions into team context, running scheduled queries:

# .github/workflows/ox-distill.yml
name: ox distill
on:
  schedule:
    - cron: "0 6 * * *"     # daily at 06:00 UTC
  workflow_dispatch:

jobs:
  distill:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ox
        run: curl -fsSL https://install.sageox.ai/ox | sh

      - name: Prime and distill
        env:
          SAGEOX_TOKEN: ${{ secrets.SAGEOX_TOKEN }}
        run: |
          ox agent prime
          ox distill --since=24h

For self-hosted runners with a persistent filesystem, ox will detect the persistent disk and use its normal local-state mode — you'll get better performance from the local CodeDB index without any config change.

GitHub Codespaces

A Codespace has persistent disk and a multi-hour lifetime. Treat it as a slow laptop, not a sandbox:

# one-time workspace setup
curl -fsSL https://install.sageox.ai/ox | sh
ox login            # one-time, opens browser via Codespaces port-forward
ox init             # connects the workspace to your repo

After the first-run setup, every subsequent terminal session in the Codespace has ox configured from local state — no PAT needed, no per-session priming.

If you'd rather skip the device-code flow, export SAGEOX_TOKEN from a Codespaces secret instead of ox login. Both work; the device flow gives you the same credential refresh story as your laptop.

Troubleshooting

SAGEOX_TOKEN expired or invalid

The PAT has expired, been revoked, or is malformed. Create a new one at Settings → Tokens and update the secret in your agent platform. See Personal Access Tokens.

401 Unauthorized against a custom endpoint

ox defaults to https://api.sageox.ai. If you set SAGEOX_ENDPOINT to a staging endpoint, confirm the PAT was issued against that same environment. PATs are bound to the endpoint they were issued for.

failed to clone team context: dial tcp: i/o timeout

Network allowlist gap. The sandbox blocked the git host. For Claude Code Cloud, add the host to network.allowed_hosts. For Devin, check the workspace network settings. For GitHub Actions, this usually means a private team-context repo requires an SSH key — use HTTPS with a Git PAT instead.

ox: command not found

The install script failed silently, often because curl was missing from a minimal base image. Use the platform's package manager to install curl first, then re-run the install script. For Devin, add the install step to the setup commands so it runs in a snapshot with a fuller toolchain.

OX_EPHEMERAL=1 set but you appear to be on a persistent machine

You exported OX_EPHEMERAL=1 in a previous shell session and forgot. Unset it to restore full functionality. ox doctor will flag this on every invocation until you do.

Auto-detection misfired

If ox runs in constrained mode when you expect full mode (or vice versa), use the capability-level overrides above (OX_PERSIST_DISK, OX_NO_DAEMON, OX_NETWORK) rather than the coarse OX_EPHEMERAL=1. Run ox doctor to see which detection rule fired and what the resulting capabilities are.

Related

• Personal Access Tokens — the credential you need first
• ox agent prime — what gets loaded at session start
• ox doctor — see capabilities for the current environment
• SageOx + Codex cookbook — recipes for OpenAI Codex