Cloud & E2B Runtime

How XibeCode cloud mode works, what runs locally vs remotely, and how to resume/pull sandbox sessions safely.

This page is the canonical runtime guide for cloud execution in XibeCode.

Local vs Cloud (Critical)

Running xibecode or xc with no subcommand runs in local mode for that process.
Running xibecode cloud or xc cloud forces E2B-backed execution for that process.
The terminal UI still runs on your machine. In cloud mode, tool execution is routed through the configured gateway/E2B session.

What Runs Where

In cloud mode, behavior depends on sandboxSessionStrategy:

`host_only`

run_command executes in the remote sandbox.
File tools still read and write your local repository.
Best when you only need isolated command execution.

`sandbox_full`

The CLI syncs your workspace to a sandbox first.
File tools and command tools run in the sandbox workspace.
You should use repo-relative paths in prompts and tool calls.
Do not rely on host absolute paths for sandbox file operations.

Core Cloud Commands

# Start cloud chat (E2B-backed for this process)
xibecode cloud

# Resume a shared/existing sandbox using sandbox ID
xibecode cloud resume <sandbox-id>

# Pull sandbox workspace back to local disk (extracts to a timestamped folder under .xibecode/)
xibecode cloud pull --session <session-id>

# Merge sandbox files into the current directory (default: only new or changed files; skips identical copies)
xibecode cloud pull --session <session-id> --apply

# Legacy: extract the full archive over cwd (every path from the archive is written)
xibecode cloud pull --session <session-id> --apply --full

With --apply, the CLI still downloads the full workspace archive from the gateway (the export is a complete tree), but it extracts to a temporary directory and then copies into your project only when:

the file is missing locally, or
the file exists but content differs (size or bytes).

Identical files are left untouched. Files that exist only on your machine are not deleted when they are absent from the sandbox archive.

Use --apply --full for the previous behavior: extract the entire tarball directly into the working directory.

In-chat pull shortcut

Inside interactive cloud chat, you can use:

/cpull
/cpull --apply
/cpull --apply --full
/cpull --output .xibecode/sandbox-pull-manual

/cpull is only available in sandbox_full sessions. Options match the CLI (--apply, --full, --force, --output <path>).

Preview URLs

When your sandbox runs a web server, preview URLs are typically:

https://{port}-{sandboxId}.e2b.dev

The exact host may differ when the gateway returns a provider-specific host from E2B.

Gateway and Auth Resolution

For gateway URL and auth token, the CLI resolves values in this order:

Runtime environment variables (XIBECODE_SANDBOX_*)
Saved profile/config values (xibecode config --set-sandbox-*)
Built-in defaults configured by the distributor

This keeps defaults simple for hosted usage while allowing self-host overrides.

Team E2B gateway: pause and auto-resume

If you self-host packages/e2b-gateway, sandboxes are created with pause on idle timeout (not kill) and auto-resume on the next gateway request, SDK operation, or HTTP hit to a preview URL—matching E2B’s lifecycle behavior.

XIBECODE_E2B_SANDBOX_TIMEOUT_MS — milliseconds of inactivity before pause (default 900000, i.e. 15 minutes). Increase if chats go quiet for long stretches.
XIBECODE_E2B_TEMPLATE — your published template id or alias (unchanged).

See packages/e2b-gateway/.env.example for copy-paste variables.

Cloud Configuration Flags

Use these persistent config commands:

xibecode config --set-sandbox-mode e2b
xibecode config --set-sandbox-gateway-url "https://your-gateway.example.com"
xibecode config --set-sandbox-auth-token "your-shared-token"
xibecode config --set-sandbox-session-strategy sandbox_full
xibecode config --set-sandbox-sync-max-mb 50
xibecode config --set-sandbox-sync-exclude ".git,node_modules,.xibecode,dist,build,.env,.env.*"
xibecode config --set-sandbox-sync-respect-gitignore true

Environment Variables Reference

These are the cloud-related runtime variables used by the CLI:

XIBECODE_SANDBOX_MODE (local or e2b)
XIBECODE_SANDBOX_SESSION_ID (reuse an existing session id)
XIBECODE_SANDBOX_SKIP_SYNC (1/true skips initial sync)
XIBECODE_SANDBOX_GATEWAY_URL
XIBECODE_SANDBOX_AUTH_TOKEN
XIBECODE_SANDBOX_STRATEGY (host_only or sandbox_full)
XIBECODE_SANDBOX_SYNC_MAX_MB
XIBECODE_SANDBOX_SYNC_EXCLUDE
XIBECODE_SANDBOX_SYNC_RESPECT_GITIGNORE

xibecode cloud resume <sandbox-id>

Then they can pull changes with xibecode cloud pull or /cpull.