How Perplexity SPACE saves agent work and handles credentials

A coding agent needs somewhere to run commands, install dependencies, and test its changes. A sandbox gives it an isolated environment for that work. Once you run many agents, you also need to decide how to save their progress, copy an environment for another task, and let them call services that require credentials.

Those details affect the workflow you can build. Does copying a sandbox preserve a running program? Does pausing it free the server’s memory? Where is an API key added to an outgoing request? A feature list can leave those questions unanswered.

Perplexity released SPACE as open source on October 15. It runs agent code in Firecracker microVMs, small virtual machines with their own operating-system kernels. We used a GitHits-enabled agent to inspect its implementation at commit b9fc395, the revision indexed from the default branch on October 16.

The agent searched and read the repository through 48 GitHits calls without cloning it. The findings below describe that revision. We inspected source and documentation; this article doesn’t report a deployment test or security audit.

What gets saved when an agent stops working?

SPACE distinguishes pause from suspend. Pausing stops the virtual CPUs, which are the processors visible inside the sandbox, while keeping its memory on the host server. It allows the VM to resume, but it isn’t a durable saved copy.

Suspending writes a snapshot: saved memory, VM state, and files that can be used to restore the environment. It then releases the VM’s resources. API-created sandboxes suspend after six hours without activity by default.

The implementation uses Firecracker’s pause and resume operations and snapshot operations. SPACE requests a Diff snapshot, which writes memory regions changed since the previous snapshot. The code calls these changed regions “dirty pages.” This avoids writing the full memory contents each time. A comment records that full snapshots wrote the whole memory file on every suspend and that the change to diff snapshots didn’t slow restoration in the team’s measurements.

There are also two kinds of saved sandbox data: DISK saves the filesystem, while FULL includes VM state and memory. That distinction becomes important when copying a sandbox.

What happens when you copy a running sandbox?

SPACE calls this operation a fork. It creates a new sandbox from an existing one. You might use it to give another agent the same installed tools and files.

The fork process first checks that the source belongs to the caller’s organization. It records the settings the new sandbox should inherit, including the template, environment variables, resource limits, and network rules. The source must be running, paused, or suspended.

For a running or paused source, the implementation requests a disk snapshot. The new sandbox therefore starts with the source’s files. Programs that were running in the original need to be started again in the copy; their live memory isn’t included. A suspended source follows a different path that copies its already-saved suspend artifact.

SPACE checks which execution of the source it is copying. If the source changes during capture, it retries up to three times before failing. Concurrent fork requests share a capture. The saved data is uploaded to object storage and restored into a new sandbox, with one target sandbox per fork operation.

For a workflow that copies an agent environment, the practical question is what must be restarted after restoration. Files written to disk can be available in the copy; a running development server needs a new process.

How a request gets its API credentials

An agent may need to call an external API without holding its real access token inside the sandbox. SPACE supports this by adding credentials at a network gateway, a service outside the VM that handles its outgoing requests.

A credential rule identifies the destination host, port, optional path prefix, allowed request methods, and the secret to add to an HTTP header. The allowed methods at this revision are GET and POST.

For HTTPS requests covered by this feature, the gateway handles TLS encryption so it can inspect the request. It matches the destination against the rule and retrieves the configured header value. It adds that value after removing routing headers controlled by the sandbox. A test checks that a placeholder authorization header from the sandbox is replaced with the configured secret before forwarding.

The failure cases matter too. Tests show that a missing required credential, or a credential-bearing request that tries to switch to WebSocket, gets a 403 response without a connection to the destination. Destinations exempted from TLS interception skip this inspection and credential injection.

The configuration reference describes retrieving secrets from AWS Secrets Manager. An organization-specific access role limits which secrets can be read. Without that role, the credential references can’t be resolved.

This gives a team concrete compatibility checks: do its API calls use the supported methods, match the configured destinations, and pass through the gateway’s inspection path?

Which network destinations are blocked?

Egress means outgoing network traffic. SPACE lets an organization configure egress rules, but the service also has a fixed list of blocked address ranges. Those include internal SPACE addresses, local address ranges, and the cloud machine’s metadata service, an endpoint that can provide machine credentials.

A gateway test checks that the metadata service stays blocked even when the organization’s policy allows all destinations. The policy documentation also states that explicit organization and platform denies take priority over additional allowances. Forks inherit the source’s saved egress policy.

These checks describe specific restrictions in the code. They give you a starting point for assessing how your own agent traffic would be handled.

What can you deploy at this revision?

The code names three possible runtimes, the components that run the isolated environments: Firecracker, Cloud Hypervisor, and gVisor. The driver registry contains an implementation for Firecracker and rejects the other two as unsupported. The names in the type definitions therefore don’t establish working support.

Sandbox templates supply the initial operating system and installed tools. SPACE’s code-runtime template builds on a minimal Ubuntu template and adds Python, Node.js, Jupyter, and developer tools. Existing sandboxes keep their template release when a tag such as latest moves to a new build.

A single server can keep a base snapshot of a booted template and use it to create new sandboxes. If the saved snapshot or pool is missing, creation falls back to a normal boot. The output’s boot-mode line tells you which path was used.

SPACE can also run through a direct adapter without Kubernetes, the system commonly used to manage workloads across servers. That adapter has fewer features: its documentation excludes forks and some pool-management settings, as well as moving workloads off a server for maintenance. Those operations need the Kubernetes deployment path described in this revision.

Restoring old environments after an upgrade

A saved sandbox can outlive the software running on its host. SPACE includes a small service called spaced-guest inside the VM and a matching host service, spaced-host. They exchange commands through VSOCK, a connection between a host and its VMs that doesn’t need the guest’s network. The host checks the identity of local callers, allowing root or the sandbox-manager account.

Because the guest service is included in templates and snapshots, upgrading a host must preserve compatibility with saved environments. The supported guest-version range is >=0.1.0, <0.9.0 at this revision. A comment says to keep support for older guests until live environments, templates, and dormant snapshots have a migration path. The versioning guide warns against relabeling old snapshots to make them pass a version check.

Use the findings to check your workflow

If you’re evaluating SPACE, start with the operations your agents need. A fork of a running sandbox preserves files and requires processes to restart. Credential injection has specific destination and request-method rules. Running without Kubernetes is possible, but it removes features that may matter for copying or moving environments.

Reading the code made those limits visible. GitHits gave the agent access to a specific repository revision and the file locations behind its answers. You can use the same approach when evaluating public dependencies for your own agents. Set up GitHits with npx githits@latest init.

The research prompt and tool calls

For readers who want to repeat the source inspection, here is the original technical prompt and a sample of the calls. It names the implementation details discussed above.

These are the questions we gave the agent:

Explore github:perplexityai/SPACE with GitHits at commit
b9fc395e06189460262c261b8bf34dfa5a305745. Verify the
spaced-host/spaced-guest VSOCK bridge and its authorization;
how pause/resume, snapshot, and fork are implemented;
per-session credential isolation and network egress controls;
whether the runtime abstraction has anything besides fc
(Firecracker); and how templates are built and SPACE runs
without Kubernetes. Ground every claim in code you read through
GitHits, with permalinks pinned to the commit. If something is
not in the code, say so.

A few of the calls it made, with their main arguments (all against the same target):

search  target: github:perplexityai/SPACE@b9fc395e06189460262c261b8bf34dfa5a305745
        query:  "pluggable runtime trait implementation Firecracker fc runtime backend"
grep    pattern: "pub enum RuntimeKind"   corpus: source
grep    pattern: "const CREATE_SNAPSHOT_TYPE"
        path prefix: crates/libs/node/runtime/core/src/
read    path: crates/libs/api/src/controllers/substrate/direct.rs   lines 1-120

The first search returned the Firecracker client and tests. The agent then used grep to find the list of runtime names and followed their uses to the driver registry. That is how it established which runtimes had an implementation.