Cloud Managed Sandbox

Appaloft Cloud provides a ready-to-use managed Execution Sandbox: create, connect to, run commands, files, and processes in, and clean up a Sandbox without registering your own server. It uses the exact same Sandbox operations and SDK as self-hosted Appaloft; Cloud only adds a managed worker, isolation policy, and credential broker so you don’t have to operate the underlying machine.

Relationship To Self-Hosted Sandbox

Sandbox itself is a public Appaloft capability: create, pause/resume, exec, file transfer, process/port management, snapshot, and cleanup all go through the same CLI/HTTP/API/SDK regardless of who hosts it. The only difference for Cloud managed Sandbox is who provides the underlying machine:

• Self-hosted: the Sandbox runs on a server you registered with Appaloft; you own that machine’s availability and cost.
• Cloud managed: the Sandbox runs on a worker Appaloft Cloud provides or manages; you receive only a scoped Sandbox handle and never need to see or manage the underlying VPS/SSH/Docker details.

If your organization has already registered its own servers with Appaloft Cloud, and no target policy is saved, Cloud uses that registered Server and does not require managed capacity. An Owner or Admin can still explicitly save registered-server or managed. A saved managed policy never automatically switches to your servers when managed capacity is unavailable.

Managed Target Selection For appaloft code

After signing in to Appaloft Cloud, run appaloft code from a clean, pushed Git repository:

1. If the current Project or organization has a saved registered-server policy, only eligible registered Servers in that organization are used. A Project policy overrides its organization.
2. If no policy is saved and the organization already has an eligible registered Server, Cloud uses that Server as registered-server/platform-default. This path does not require managed entitlement and does not enroll another Server. appaloft code --server <id> remains an explicit selection.
3. If no policy is saved, no eligible registered Server exists, and the account has managed Workspace entitlement, Cloud selects managed/platform-default and creates or reuses the minimum Project, Repository Binding, and default Workspace Profile in the same request. This path does not require appaloft server enroll first.
4. If the effective choice is managed (a saved managed policy, or no eligible registered Server) but entitlement, health, or capacity is unavailable, the request fails explicitly before Sandbox creation. A saved managed request never silently falls back to a registered Server or the local machine. To change the default to your own machine, have an Owner/Admin save registered-server.

Workspace results, status, and the TUI show the same safe evidence: target class, selection source, and reason, such as managed/platform-default. These fields never contain a Server id, host, provider handle, capacity total, or credential.

Owners and Admins can change organization or Project policy on the Workspace target policy page in Cloud Console. Developers can read the effective result but cannot mutate it. Automation can use:

GET /cloud/workspace-target-policy?projectId=<project-id>
PUT /cloud/workspace-target-policy

The PUT body contains scope, targetClass, an optional projectId, and a required expectedRevision; use null for the first write. A stale revision returns a conflict instead of overwriting another administrator’s newly saved policy.

Isolation Model

The first available isolation tier for Cloud managed Sandbox is honestly labeled container-trusted: a real container boundary, without a claim of hostile-multi-tenant-grade isolation. Stronger isolation tiers (for example a gVisor-backed runtime) roll out progressively once available and verified; this page is updated when the isolation tier changes rather than silently marketing container-trusted as fully isolated.

High-risk or anomalous Sandbox creation requests may be denied by admission policy, or required to use a stronger isolation tier.

Credential And Network Boundary

• Cloud never exposes underlying VPS, SSH, Docker, or server credential fields to callers; you always receive a scoped Sandbox handle and an Appaloft-issued token, never a credential that can connect directly to the underlying machine.
• When a Sandbox needs to reach an external service (for example a model API or Git credentials), Cloud issues a short-lived, purpose-bound credential grant. Long-lived secrets are never injected in plaintext into Sandbox environment variables or logs; if the credential broker is unavailable, the request fails explicitly instead of falling back to plaintext injection.
• A Sandbox has no arbitrary outbound network access by default. Access to a specific external service is granted through an explicitly declared credential/network capability, not by opening the Sandbox’s entire outbound network.

Connect A Model Provider

Open Organization Settings → Agent workspaces → Model connections, choose OpenCode or Pi, then connect DeepSeek, OpenAI, Anthropic, or an OpenAI-compatible provider. A model API key is submitted once and encrypted immediately by Cloud credential custody; lists, logs, Task input, argv, and audit surfaces expose only redacted connection metadata.

A provider connection is not an Agent Adapter: the Adapter describes how the Agent runs, while the Model connection supplies the owner-scoped credential it uses to call a model. Never paste the key into an Adapter or Profile manifest. Codex is absent from this Pi/OpenCode V1 setup path until its real-provider acceptance is complete.

Use Existing Agent Configuration On A Registered Server

existing-server-config is for credentials an owner or organization already keeps on its own registered Server. It never mounts the SSH login user’s or root’s HOME. Cloud Console returns a serverHomePath, for example:

/var/lib/appaloft/runtime/agent-homes/tenant_alpha/organization/org_alpha/opencode

Create that directory on the target Server with mode 0700, then copy the required files from an already authenticated Agent HOME. Each source must be a regular non-symlink file no larger than 1 MiB; materialized files use mode 0600.

APPALOFT_AGENT_HOME=/var/lib/appaloft/runtime/agent-homes/tenant_alpha/organization/org_alpha/opencode
sudo install -d -m 700 "$APPALOFT_AGENT_HOME/.local/share/opencode"
sudo install -m 600 "$HOME/.local/share/opencode/auth.json" \
  "$APPALOFT_AGENT_HOME/.local/share/opencode/auth.json"

Then choose the owner, OpenCode or Pi, Server pool, allowed Projects/Profiles, and unattended policy under Existing server config in Cloud Console. ownerScopedHomeRef is derived from the owner and Agent by default; it is not a filesystem path and must not name another owner. Codex remains explicitly deferred for this mode.

Every Agent Runtime receives its own /workspace/.appaloft-agent/runtime-home/<runtimeId> as HOME, so sibling Runtimes in one Sandbox do not share credentials or sessions. Credential files are copied directly on the same registered Server and never cross a control-plane response, log, or argv. Run completion removes only the allowlisted files for that Runtime; Sandbox pause, snapshot, or termination removes allowlisted files from every Runtime while preserving Agent sessions and other durable state. Resume or a control-plane restart revalidates the Connection and materializes it idempotently.

Configure Remote MCP For An Agent Workspace

An organization Owner or Admin can connect an external HTTPS MCP server to a Pi or OpenCode Workspace from Model connections in Cloud Console:

1. Create a Named MCP credential with a stable name, display name, and bearer token. Appaloft returns only an opaque reference; the raw token never appears in responses, logs, audit, Workspace Profiles, or Sandboxes.
2. Create a Remote MCP Connection, select that named credential, enter a credential-free HTTPS Streamable HTTP endpoint, and declare allowed read tools separately from explicitly approved write tools.
3. Bind the Connection to an MCP requirement declared by a Workspace Profile. Workspaces opened with that Profile receive a short-lived Gateway capability scoped to the exact Runtime, Run, and tool—not the upstream endpoint or token.

A named MCP credential belongs to the organization but is not represented as an Agent credential or Model Connection. Rotation keeps its opaque reference stable while new requests use the new version. Revocation makes new resolution and calls fail closed even if a Connection record remains; disabling or revoking the Connection also fences issued capabilities. Never put the token in an Adapter manifest, Workspace Profile, environment template, or custom launch arguments.

Quota And Availability

Sandbox concurrency, time-to-live (TTL), and resource sizing are governed by your organization’s current entitlement. Requests that hit a quota limit return an explicit quota error instead of queueing or silently degrading. See your organization settings in Cloud Console for the current quota values; this page does not maintain specific numbers that change with pricing. Managed worker capacity also counts allocations held by running managed Sandboxes; it is released on termination or controlled orphan cleanup, so a short-lived create reservation is not mistaken for the complete running-capacity record.

Common Questions

Is a Sandbox the same as a Deployment? No. A Deployment targets a long-running application; a Sandbox targets a short-lived, interactive, or agent-driven execution environment with its own pause/resume/snapshot/cleanup lifecycle. The two can coexist, but a Sandbox should not be used as a deployment target.

How is a Cloud managed Sandbox different from a plain Docker container? A Cloud managed Sandbox adds tenant isolation, admission policy, a credential broker, and audit on top of the container boundary; a bare container provides none of those guarantees.

Related Tasks

• The Agent Workspace page under Agent 与 Sandbox / Agents: how Agent Workspace uses a Sandbox to host its runtime.
• CLI/HTTP/API reference: full command and field reference for the sandboxes operation.