How to Set Up Perplexity SPACE: Deploy a Sandbox and Run Your First Command

Learn how to set up Perplexity SPACE, configure its local deployment, authenticate with the API, create an isolated sandbox, run a command, inspect output, and clean up safely.

Perplexity SPACE is an open-source sandbox platform designed to give AI agents an isolated place to execute code and work with files. Instead of letting an agent run arbitrary commands directly on a developer’s host, SPACE places workloads in short-lived virtual environments and exposes an API for creating sandboxes, running commands, collecting output, and managing their lifecycle. Perplexity introduced SPACE as the sandbox platform behind its Computer agent and has published the project and its developer documentation for people building agentic systems.

This guide explains what SPACE does, how to prepare a compatible Linux machine, how to follow the official local deployment instructions, and how to run a first command through the API. It also covers authentication, troubleshooting, cleanup, and security considerations. The instructions focus on the documented local-development path. Your exact commands may differ as the project evolves, so use the current official guide as the source of truth when a repository instruction changes.

Important before you start: SPACE is a developer infrastructure project, not a one-click feature inside the regular Perplexity chat interface. Its local deployment has host and virtualization requirements. Read the prerequisites before allocating time to installation, and do not assume that a laptop or cloud virtual machine supports the required virtualization features.

What is Perplexity SPACE?

SPACE stands for a sandbox platform for agentic code execution. It provides an API and runtime for creating isolated environments in which an AI agent or application can execute commands. The platform uses Firecracker microVMs, a lightweight virtualization technology, to separate sandbox workloads from the host environment. A sandbox has its own writable filesystem and runtime, and it can be created, inspected, paused, resumed, or deleted through the platform’s management interface.

The key concepts are:

Template: A reusable starting environment that defines the base filesystem and runtime configuration.
Sandbox: An instance created from a template. It has its own environment and writable filesystem.
Command session: A session for running a process and collecting its output.
Operation: A record used to track asynchronous lifecycle work, such as creating or deleting a sandbox.
Management API: The authenticated interface for creating sandboxes, managing commands, and checking operation status.
Data plane: The endpoint used to attach to command output streams. It can use a separate, session-scoped token.

These pieces are useful for agent developers because a task may need to create files, install or invoke tools, execute code, and inspect results without granting the agent unrestricted access to the machine running the application. Isolation reduces risk, but it is not a substitute for careful permissions, network policy, secrets handling, or monitoring.

SPACE is distinct from a hosted chat feature. The open-source repository and guides let developers deploy and operate the infrastructure themselves. That means you are responsible for prerequisites, configuration, authentication, updates, and the security of the environment in which you run it.

What you need before installing

Check these items before cloning the repository:

A supported Linux x86_64 host. The documented local deployment path is built around Linux and hardware virtualization. Do not assume that the same setup works directly on macOS or Windows.
KVM support. The host must expose the virtualization capabilities needed by the microVM runtime. A cloud VM may need nested virtualization enabled by its provider.
Container and cluster tooling. Follow the current installation guide for the required Docker and Kind setup. Kind runs a local Kubernetes cluster in containers; it does not remove the host’s virtualization requirements.
Administrative access for setup. Some prerequisite packages and system services may require elevated privileges. Review each command before running it.
A Bash shell and a supported Python version. The first-sandbox guide uses Python’s standard library, but the local setup instructions rely on shell environment variables remaining available.
Enough disk space and memory. The local cluster, images, and sandbox templates need resources. Check current project guidance and the capacity of your host rather than assuming a small machine will be sufficient.
A test environment. Start with a disposable development machine or isolated cloud VM, not a production server containing sensitive credentials.

To verify virtualization, inspect the Linux distribution’s documentation and the virtualization status exposed by your host. If you are using a cloud VM, confirm nested virtualization support with the provider. If KVM is unavailable, stop and resolve that prerequisite before continuing; repeatedly running the installer will not create missing hardware support.

Step 1: Read the official installation guide

Begin with the official SPACE repository and the Install and configure locally guide. Check the documented prerequisites and follow the instructions in order. The repository is the source for the code; the documentation explains the expected deployment and authentication flow.

Clone the repository using the URL documented by the project:

git clone https://github.com/perplexityai/SPACE.git
cd SPACE

If you already have a checkout, enter that directory and review its current branch and changes before updating it. Avoid mixing unrelated local edits with installation troubleshooting.

The official guide describes setting up the local cluster, deploying the required services and templates, and configuring access to the management API and data plane. Follow those instructions one complete block at a time. Do not skip ahead to the first-sandbox example until the deployment and authentication steps have completed successfully.

Why not copy a fixed list of installation commands here? Infrastructure projects change package versions, environment names, and setup steps. Using the maintained installation guide prevents this article from freezing a command sequence that may become outdated. The stable workflow is to clone the official repository, satisfy its host prerequisites, deploy the documented local stack, and verify the API configuration before making requests.

Step 2: Keep the shell environment consistent

SPACE’s local setup exports environment variables used by later commands. The official guide documents variables such as:

SPACE_API_URL: the base URL for the management API, before the /v1 path.
SPACE_DATA_PLANE_URL: the endpoint used for command output streams.
SPACE_API_TOKEN: the bearer token used for management requests.
SPACE_TEMPLATE: the template to use when creating a sandbox; the first-sandbox example documents seed:latest as its default.

Use the values and authentication method provided by your deployment. Do not copy tokens from a screenshot, example, or another machine. Treat tokens as secrets and avoid committing them to Git, adding them to shell history, or pasting them into public issues.

The setup instructions expect the environment to remain available in the same Bash session. If you open a new terminal, reconnect to the documented session or repeat the appropriate environment setup and authentication steps. A common source of confusion is running the example in a shell that does not contain the exported variables.

You can check whether variables are set without printing the token itself:

test -n "${SPACE_API_URL:-}" && echo "Management API URL is set"
test -n "${SPACE_DATA_PLANE_URL:-}" && echo "Data plane URL is set"
test -n "${SPACE_API_TOKEN:-}" && echo "Management token is set"

These checks only confirm that values exist. They do not prove that the URLs are reachable, that the token is valid, or that the deployed services are healthy. Use the official health checks and troubleshooting instructions to validate those conditions.

Step 3: Create your first sandbox

Once the local deployment is ready and authenticated, open the official Your first sandbox guide. It demonstrates the full lifecycle: create a sandbox, run a command, collect its output, and delete the sandbox when finished.

The example uses Python’s standard library, so it does not require a separate SDK installation or virtual environment. Run it from the repository root on the same Linux host where the local setup and environment variables are available. Use the current example from the guide rather than inventing endpoint paths or payload fields; API contracts can evolve, and a malformed request can obscure whether the deployment itself is working.

At a high level, the example performs the following operations:

Sends an authenticated request to create a sandbox from a template.
Waits for the creation operation to finish and obtains the sandbox details.
Requests a command session for a simple test command.
Attaches to the command stream and reads the process output.
Checks the command result and reports the output.
Deletes the sandbox and waits for the lifecycle operation to complete.

Start with a harmless command such as printing a short message or checking the runtime version. Avoid testing with commands that access personal files, read environment secrets, modify the host, or connect to external systems. A first run should establish that the API, sandbox lifecycle, command execution, and output stream are working—not test the limits of the environment.

Step 4: Understand the two authentication contexts

One important detail in the SPACE documentation is that management requests and command-output streams use different credentials. The management API uses the configured bearer token. When a command session is created, the response supplies a separate session-scoped attachment token for connecting to the data plane.

Do not interchange the two tokens. A management token is not automatically the right credential for a command stream, and the attachment token is not a replacement for the management credential. Keep each token in memory only as long as needed and do not log full authorization headers.

The first-sandbox example also takes care to validate the attachment destination and avoid unsafe redirects. This matters because an agent execution system handles URLs and credentials across multiple services. If you adapt the example for your own application, preserve the documented origin checks, HTTPS requirements, and token separation rather than simplifying away security controls.

When integrating SPACE with an agent framework, keep the API client behind a narrow application interface. Give the agent only the operations it needs, validate inputs before creating a sandbox, set sensible timeouts, and record lifecycle outcomes without logging secrets. If the integration supports user-supplied code, assume that code may be malicious or simply behave unexpectedly.

Step 5: Verify that the command actually ran

A successful HTTP response does not necessarily mean the requested command completed successfully. SPACE models several actions as asynchronous operations. A request can be accepted while the underlying operation is still in progress.

For a reliable first test, verify each stage:

The sandbox creation operation reaches a successful terminal state.
The returned sandbox identifier is present and refers to the expected sandbox.
The command session is created successfully.
The data-plane stream connects to the expected endpoint.
The output contains the expected test message.
The process result indicates success, rather than merely returning some output.
The sandbox deletion operation completes.

If a command prints the expected text but exits with a non-zero status, treat the test as failed until you understand why. Likewise, do not call a deployment healthy solely because the management endpoint responded. Confirm the command path end to end.

For more detail about object lifetimes and lifecycle operations, read the official SPACE architecture guide. It explains how a sandbox, lifecycle operation, and command stream can have separate lifetimes. That distinction is useful when debugging a request that appears to have timed out even though the underlying operation is still running.

Step 6: Clean up the sandbox

The first-sandbox example includes deletion because cleanup is part of the test, not an optional afterthought. A sandbox may have a lifecycle that extends beyond the HTTP request that created it. Explicitly delete test environments when they are no longer needed and wait for the deletion operation to complete.

For an agent service, implement cleanup in a reliable finalization path so that ordinary success, application errors, and user cancellation do not leave unnecessary environments running. Also define a timeout or reconciliation process for cases where the client loses its connection before it can confirm the result. Check the platform’s current lifecycle semantics before assuming that a disconnected client means the sandbox has stopped.

Do not place valuable data in a disposable sandbox unless your workflow explicitly exports it to a controlled destination. The isolated filesystem is part of the execution environment, not a substitute for durable storage or backup. Before deleting a sandbox, ensure that any output you need has been collected and stored according to your data-handling policy.

Troubleshooting common setup problems

The deployment cannot access KVM

Check whether the host supports hardware virtualization and whether the operating system or cloud provider exposes it to the environment. If you are inside a virtual machine, nested virtualization may need to be enabled. Resolve the host-level issue first; changing API tokens will not fix unavailable virtualization.

The example says an environment variable is missing

Confirm that you are in Bash and that you followed the setup and authentication steps in the same session. A new terminal does not necessarily inherit variables exported in another shell. Repeat the documented configuration steps without displaying secrets in your terminal output.

The management API cannot be reached

Check the configured API URL, service status, and local port-forwarding steps from the installation guide. Confirm that the URL is the base endpoint expected by the guide, not a URL copied from an unrelated example. Use the deployment’s current health checks and inspect service logs for more detail.

Authentication fails while reading command output

Verify that the management request used the management bearer token and that the stream connection used the attachment token returned for that command session. Also confirm that the attachment URL belongs to the configured data-plane origin. Do not work around a failed origin or certificate check by disabling validation.

Sandbox creation is still pending

Creation and deletion may be tracked as asynchronous operations. Poll or wait using the procedure in the official example, and inspect the operation state before submitting duplicate creation requests. If the operation fails, use its error details and the deployment logs to identify the failed component.

The command returns output but the test fails

Inspect the process status and the command stream’s completion information. Output alone does not establish a successful exit. Repeat the test with a simple command and compare its expected output and exit status.

The sandbox is not deleted after a client error

Check the sandbox’s lifecycle state through the management API and follow the documented deletion workflow. Build cleanup and timeout handling into production integrations. If a client loses connectivity during deletion, verify the actual state before retrying or assuming the environment is gone.

Security practices for agent sandboxes

Isolation is a valuable layer of defense, but secure deployment still requires careful design. Use the following practices when experimenting with SPACE:

Start with least privilege. Give the service and agent only the permissions required for their task.
Keep secrets outside the sandbox when possible. Never pass broad host credentials or unrelated API keys into untrusted execution.
Constrain network access. Review what the sandbox can reach, especially internal services and cloud metadata endpoints.
Validate user inputs. Treat commands, filenames, templates, and task descriptions as untrusted data.
Use time and resource limits. Prevent runaway processes from consuming excessive CPU, memory, storage, or execution time.
Log outcomes safely. Record identifiers, status, and relevant errors while redacting tokens and sensitive command output.
Keep the runtime updated. Track the upstream repository and its security guidance, and review changes before upgrading production deployments.
Test cleanup and failure paths. Verify that cancellation, API errors, and process timeouts do not leave workloads running unexpectedly.

For threat modeling, consider not only a malicious command but also an agent that misunderstands a task, follows a prompt injection, or attempts an action outside its intended scope. The sandbox can reduce the consequences of execution, but the surrounding application must still decide which tasks are permitted and what resources the environment can access.

Is SPACE ready for production?

The open-source release gives developers a way to inspect the implementation and experiment with the platform. It does not mean every deployment is automatically production-ready. Evaluate operational maturity against your requirements: authentication and authorization, tenant isolation, network controls, observability, update strategy, resource limits, disaster recovery, and the handling of untrusted workloads.

Before using SPACE for customer-facing agent execution, run a threat model and security review. Test that one sandbox cannot access another sandbox’s data, that network restrictions work as intended, that expired or invalid credentials are rejected, and that cleanup is reliable after failures. Review the upstream security notes and issue tracker for known limitations that may affect your deployment.

For a learning project, begin with a local test and harmless commands. For a production service, treat the sandbox platform as a security-sensitive infrastructure dependency and build monitoring, access control, and incident response around it.

Frequently asked questions

Is SPACE a feature in the normal Perplexity chat interface?

No. SPACE is a developer platform for sandboxed code execution. Its public repository and documentation are intended for developers building or operating agent systems, rather than people who simply want to ask questions in Perplexity’s chat interface.

Can I install the documented local setup directly on macOS?

The documented local deployment path targets Linux and depends on KVM-based virtualization. Do not assume it runs directly on macOS. Use a compatible Linux host or a cloud environment that explicitly supports the required virtualization features.

Do I need a Python package to run the first example?

The documented first-sandbox example uses Python’s standard library, so a separate SPACE SDK is not required for that example. You still need to complete the local deployment and authentication steps first.

Why does SPACE use a separate token for command output?

The management API and data plane have different roles. The management token authorizes lifecycle and command-management requests, while the command session supplies a separate token for attaching to its output stream. Keeping these credentials separate limits accidental misuse.

Does deleting the sandbox delete my exported results?

Deletion concerns the sandbox environment. Any output you deliberately saved elsewhere may remain in that destination. Decide what needs to be retained, export only the necessary results, and verify the actual lifecycle behavior documented for your deployment.

Is every command guaranteed to run successfully?

No. A command can fail because of application errors, missing tools, timeouts, resource limits, or an unhealthy deployment. Check the process status and operation state, not just whether the API accepted the request.

Final checklist

Before considering your first SPACE experiment complete, make sure that you have:

Confirmed Linux and virtualization prerequisites.
Followed the current official local installation guide.
Completed authentication and kept the required environment variables available.
Created a sandbox using the documented example.
Run a harmless command and verified both output and exit status.
Used the correct token for the management API and command stream.
Deleted the test sandbox and confirmed the lifecycle operation completed.
Avoided exposing credentials or giving untrusted code unnecessary access.

Perplexity SPACE is most useful when you need a controlled execution environment for an AI agent—not simply another chat interface. A careful local test helps you understand its lifecycle and API before integrating it into a larger agent system. Keep the official documentation close at hand, preserve its security checks, and treat isolation as one component of a broader defense-in-depth design.