Cloud & E2B Runtime

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.
• Plain xibecode resume resumes host-stored sessions locally — it does not pick up global E2B / sandbox_full from profile alone.
• To continue a shared cloud sandbox, use explicitly:

xibecode cloud resume <sandbox-id>
# or
xibecode resume cloud <sandbox-id>

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.
• 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

What --apply does (default)

With --apply, the CLI still downloads the full workspace archive from the gateway, but 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 only on your machine are not deleted.

Use --apply --full to extract the entire tarball directly into the working directory.

In-chat pull shortcut

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

/cpull is only available in sandbox_full sessions. Options match the CLI.

Runtime modes on hosted sandboxes

When the daemon runs inside an E2B (or similar) sandbox — e.g. a always-on Telegram box — it uses runtime mode e2b (auto-detected or XIBECODE_RUNTIME_MODE=e2b):

Local host daemons use mode default (no auto self-update restart).

CLI update anywhere (never silent):

xibecode update --check
xibecode update --apply --yes
xibecode update --apply --yes --to 1.17.0

Disable checks: XIBECODE_DISABLE_UPDATE_CHECK=1 or XIBECODE_DISABLE_AUTO_UPDATE=1.

Preview URLs & Vite

Typical shape:

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

For Vite apps in the sandbox, configure:

// vite.config — required so e2b.dev host is allowed
server: {
  host: '0.0.0.0',
  allowedHosts: true, // or include '.e2b.dev'
}

Without this, the preview may show “host is not allowed”.

Browser / screenshots in the sandbox

• Playwright is not a CLI dependency (no Chromium download on npm install).
• Prefer agent-browser for take_screenshot (then headless Chrome/Chromium).
• Official E2B templates may ship agent-browser + Chrome for Testing + a pinned xibecode tarball.
• Screenshot paths must be workspace-relative (e.g. screenshots/home.png). Absolute /tmp/... paths are remapped into screenshots/.
• Include MEDIA:path in the final reply (or rely on auto-attach) so Telegram delivers the PNG.

Override browser preference: XIBECODE_PREFERRED_BROWSER=chrome.

Gateway and Auth Resolution

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

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

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.

• XIBECODE_E2B_SANDBOX_TIMEOUT_MS — inactivity before pause (default 900000, 15 minutes).
• XIBECODE_E2B_TEMPLATE — published template id or alias.

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

Cloud Configuration Flags

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

• 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_RUNTIME_MODE (default | e2b — daemon inside sandbox)
• XIBECODE_E2B_TEMPLATE
• XIBECODE_E2B_SANDBOX_TIMEOUT_MS
• E2B_SANDBOX_ID (or file /run/e2b/.E2B_SANDBOX_ID)

FAQ

Is the full CLI running inside E2B and streamed back?

For xibecode cloud from your laptop: no — the CLI process and chat UI run locally; tool execution is remote.

For a hosted daemon installed inside a sandbox (Telegram 24/7 box): yes, the daemon process lives in the sandbox; clients are messaging apps, not a streamed TUI.

Why do some paths fail in sandbox_full?

The sandbox does not share your host absolute paths. Use paths relative to the synced repo root.

How do I share work with another user?

Share the sandbox ID:

xibecode cloud resume <sandbox-id>

Then pull with xibecode cloud pull or /cpull.

How do I get the latest CLI on a live sandbox?

Use /update yes in Telegram (or the dashboard Update control), or rebuild the E2B template so new sandboxes ship a newer pin.

Related

• Xibe Daemon — /cmd, /update, media, steer
• Chat slash commands
• Configuration