Environments: plug in your own dev

You changed one or two services and want to run them in a box, while everything else stays on the dev you already have: the same database, the same Redis, the internal services you did not touch. Environments do exactly that.

An environment is one of your dev (or staging) setups, made of three things:

• Connections: a connector you run inside your own network. It connects out to ParallelSandbox, so your firewall needs no inbound rule. Boxes reach only the host:port you list on the connection. An environment can have several connections, one per network (a VPC, an office); each has its own token and its own address list.
• Service settings: each service's full set of environment variables in this environment, imported from AWS ECS or uploaded as a .env. In the box they are /work/.sbx/env/<service>.env and .sh.
• externalBaseUrl: where your unchanged HTTP services live (optional), same as the sandbox_start parameter.

When the agent starts a box with environment, connecting to db.internal:5432 inside the box reaches your database through your connector, from containers too, and the services you changed start with their own settings, exactly as they run on dev.

How a box reaches an address

1. At start, the box gets the environment's addresses from all its connections. Each host name gets an address of its own inside the box (from 198.18.0.0/15) that the box's DNS answers with; connections to that host:port, or to IP:port for an IP address, are routed to an entry boxd opens for the address. boxd does not listen on the address's own port, so an address on port 80, such as an internal load balancer, works like any other, and a program in the box can listen on the same port number without conflict: with your own Postgres on 5432 in the box, localhost:5432 is yours and db.internal:5432 still goes to your network.
2. When a program in the box connects, ParallelSandbox sends the connection through the connection (the network) that lists that exact host:port, and that connection's connector opens it inside your network. If two connections list the same address, the one whose name sorts first is used; list each address on the connection that can reach it.
3. DNS for your names is resolved by the connector, in your network, so private zones (Route 53 private hosted zones, Cloud Map, office DNS) work as they do for your services.
4. Containers on the default bridge, on user-defined networks and in docker compose reach the addresses the same way as the box's own programs: the box's rules apply to both, and Docker's DNS in the box forwards to the box's resolver.
5. Traffic is plain TCP end to end: TLS to your service is not terminated anywhere in between, so certificates behave as they do on your dev.
6. What the box sends through a connection counts as its outbound traffic (box_egress, Credits); what your network sends back is not metered.
7. An address can be a public host too, such as api.partner.example:443. The box then reaches it through the connector, so the traffic leaves from your own network, with its public IP address. That is the way to reach an outside service that accepts only known IP addresses: a box's own internet traffic leaves from the public IP of the host it runs on, which differs from host to host and changes as hosts come and go (Other facts).

A name you declare in the box's services that is also an environment address points at the box instead (see Use it from a box), and a link to another of your boxes with the same host:port wins over the address too (Links to other boxes). Nothing on your network can open a connection into a box: services that stay on your dev keep calling your dev's copies.

What is not listed stays out of reach, each case in its own way (observed on a box):

• A listed private IP address dialed on a port that is not listed gets no answer, like an unlisted one: the connection times out and nothing is written to private-endpoints.log.
• A listed host, or a name declared in the box, dialed on a port that is not listed or declared stays in the box: whatever listens on that port on 0.0.0.0 in the box answers, and with nothing there the connection is refused at once.
• A host name that is not listed (and not declared) is looked up by ParallelSandbox's resolver, which answers public DNS, not your private zones:
  • a name that exists only in your private DNS (Cloud Map, a Route 53 private zone, office DNS, a private API Gateway's <api-id>.execute-api.<region>.amazonaws.com) does not resolve: Could not resolve host, no such host, NXDOMAIN. List it on the connection that can reach it, with the port it is dialed on (443 for API Gateway), and the connector resolves it in your network;
  • a name that public DNS resolves to a private IP, such as an RDS endpoint or an internal-….elb.amazonaws.com load balancer, does resolve, and the connection then times out like any unlisted private IP; list it to reach it;
  • public names resolve as usual and go straight to the internet.
• A listed IP address is caught inside the box: boxd's rules send that IP and port, from the box's programs and its containers alike, to its entry for the connection.
• A private IP address that is not listed gets no answer: the connection times out, and nothing is written to private-endpoints.log.
• Port 80 is different: an address listed on port 80 itself works like any other, but a listed host or declared name dialed on 80 without being listed or declared on 80 reaches boxd's scene entry, which answers 502 nothing listens on <name>:80 in this box: that name is declared on another port. Dial the port it is declared on, or declare it on port 80 with targetPort, the port your process listens on. A box started before 2026-09-24 20:30 UTC answers with its first declared service instead.

Set it up

The agent sets an environment up over REST (below) and reads the result with sandbox_environments; there is no screen for it. Only two things need someone on your network: running the connector, and creating the AWS role if you use AWS. In order:

1. Create the environment: POST /v1/environments with a name such as dev. Agents use this name when they start a box.
2. Add a connection, one per network: POST /v1/environments/{env}/connections. The answer has a runCommand, a docker run line; its token is shown only once (and again when you rotate it). Run it on a machine in that network that can reach those databases and services (see Connector below). Within seconds sandbox_environments shows the connection as online.
3. Set the addresses of each connection: PUT /v1/environments/{env}/connections/{id}/endpoints with the whole list, one host:port each, written the way your services' settings use them, such as mydb.xxxx.ap-northeast-1.rds.amazonaws.com:5432, cache.internal:6379 or 10.0.1.5:8080. Once you have service settings, GET /v1/environments/{env}/suggested-endpoints returns the addresses found in them: every host:port in a value, every URL (without a port, its scheme's default: postgres 5432, mysql 3306, redis 6379, mongodb 27017, amqp 5672, http 80, https 443) and every *_HOST variable with a matching *_PORT, kept when the host is a private IPv4 address (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) or ends in .internal, .local, .lan, .corp, .svc, .cluster.local, .rds.amazonaws.com, .cache.amazonaws.com, .es.amazonaws.com, .mq.amazonaws.com, .docdb.amazonaws.com or .redshift.amazonaws.com. Anything else, such as an internal load balancer's internal-*.elb.amazonaws.com or a private zone with your own domain, you add by hand. List the internal names of services you might change too: boxes that do not change them reach your dev's copy, and a box that declares the name at sandbox_start takes it over.
4. Service settings: import from AWS (POST .../services/import) or upload a .env (PUT .../services/{name}), both below.

Set it up over REST

Everything above is REST on https://api.parallelsandbox.com, called with Authorization: Bearer <token>. The token is a psbx_ API key of the account, or the OAuth access token of a connected client (it expires in an hour; REST says where keys come from). The MCP tool sandbox_environments only reads: it lists environments, their connections and reachability. Creating and changing them is REST. {env} is the environment's name and {id} a connection's id from GET /v1/environments/{env}. Setting values stay write-only: reads return variable names only.

For example, an environment with one connection and one service's settings:

A=https://api.parallelsandbox.com/v1; H="Authorization: Bearer $PSBX_TOKEN"   # an API key or an OAuth access token
curl -s -H "$H" -X POST $A/environments -d '{"name":"dev"}'
curl -s -H "$H" -X POST $A/environments/dev/connections -d '{"name":"aws"}'    # token and runCommand, shown once
curl -s -H "$H" -X PUT $A/environments/dev/connections/<id>/endpoints -d '{"endpoints":[{"host":"mydb.internal","port":5432}]}'
jq -Rs '{dotenv: .}' api.env | curl -s -H "$H" -X PUT $A/environments/dev/services/api --data-binary @-

Connector

docker run -d --name parallelsandbox-connector --restart=always \
  -e PSBX_CONNECTOR_TOKEN=psbx_conn_... \
  public.ecr.aws/b2n6a1j1/connector:latest

• Run it where the targets are reachable: the same VPC, Kubernetes cluster or host as your services. On AWS, an ECS service with one Fargate task in your services' subnets and security group works well (Team setup has the commands).
• It only connects out to api.parallelsandbox.com:443 (WebSocket over TLS). Behind an HTTP proxy, set HTTPS_PROXY as usual.
• You can run several copies with the same token; boxes connect as long as one is online. When ParallelSandbox deploys a new version the connector moves to the new machines by itself: new connections use them, and connections already open keep using the old machine until it goes away, at most an hour later. Database pools reconnect on their own.
• What can be reached is decided by the addresses on the connection, enforced by ParallelSandbox first; PSBX_ALLOW lets you enforce it again on your side.
• The connector ships only as a container image (public.ecr.aws/b2n6a1j1/connector, linux/amd64 and linux/arm64); there is no separate binary download. A host without Docker needs another OCI runtime, such as Podman with the same -e variables, or run it on ECS or Kubernetes.
• If a token leaks or someone else takes over, call POST /v1/environments/{env}/connections/{id}/token: the old token stops working immediately, the running connector is disconnected, and you restart it with the new token.

Sizing and redundancy

• One connector per network serves every box of the account, whoever started it. Each connection a box opens to one of your addresses is a stream inside one of the connector's sessions (its WebSocket connections to ParallelSandbox), not a connection of its own.
• PSBX_SESSIONS (default 2, 1 to 8) is how many sessions one copy keeps open. With more than one, another session stays up while ParallelSandbox redeploys.
• For redundancy, run a second copy with the same token on another host or in another availability zone. ParallelSandbox pools the sessions of every copy: a new box connection takes a session held by the ParallelSandbox machine that received it, then one held by another machine, and last a session that is being moved away during a deploy. Every copy must reach every address listed on the connection: when the chosen copy cannot reach the target, the box gets 502 at once, without trying another copy.
• The connector only copies bytes between those streams and your targets, so the network is what it needs most. On AWS, watch the Fargate task's CPU and network metrics in CloudWatch, and give it more CPU or run another copy when they run high.
• When a box freezes or stops, ParallelSandbox closes its connections within about a minute, so they stop holding streams on the connector.
• Environments and connectors cost nothing in ParallelSandbox; what a box sends through a connection counts as its outbound traffic (Credits). The connector's own compute and network (a Fargate task, a NAT gateway, an office host) are billed by your provider.

Import service settings from AWS

ParallelSandbox reads the current task definition of an ECS service with a read-only role you grant: environment is copied as is, and the SSM parameters and Secrets Manager values (including :json-key) referenced in secrets are resolved. environmentFiles stored in S3 cannot be read and are listed under Not imported. The settings are stored under the ECS service's name unless you give another; that name is the <service> in /work/.sbx/env/<service>.env.

To bring an S3 environmentFiles file along, upload it as a .env (PUT .../services/{name}) under a second name, such as api-files, and give the service both files, that one first so the task definition's own values win as they do on ECS: docker run --env-file /work/.sbx/env/api-files.env --env-file /work/.sbx/env/api.env ..., or . api-files.sh && . api.sh. Uploading under the imported service's name would replace its imported settings.

Connect your AWS account (once per account, over REST):

1. GET /v1/aws returns the externalId the role must trust and a quickCreateUrl: opened by whoever holds the AWS account, the console shows a stack with the parameters filled in; create it. To create the role yourself: trust arn:aws:iam::580360261327:root with the condition sts:ExternalId set to that externalId, and allow ecs:ListClusters, ecs:ListServices, ecs:DescribeServices, ecs:DescribeTaskDefinition, ssm:GetParameters and secretsmanager:GetSecretValue, plus kms:Decrypt for SecureString parameters and secrets encrypted with your own KMS key. Template: https://parallelsandbox-releases.s3.ap-northeast-1.amazonaws.com/releases/aws/readonly-role.yaml.
2. PUT /v1/aws with { "roleArn": "<RoleArn from the stack's Outputs>", "region": "<region of your services>" }. ParallelSandbox signs in once and the error says why if it fails.

Then GET /v1/aws/ecs/services?region=… lists the services the role can see, and POST /v1/environments/{env}/services/import with { "region", "cluster", "service" } imports one (what could not be read comes back in sourceRef.skipped). After you deploy a new task definition, POST /v1/environments/{env}/services/{name}/sync reads it again.

Setting values are stored encrypted and handed to a box only at the moment it is claimed; agents see variable names only.

Settings for services not on ECS

For a service that runs elsewhere (Kubernetes, a VM, docker compose on a server), upload them as KEY=value lines with PUT /v1/environments/{environment}/services/{service} and { "dotenv": "KEY=value\n…" }. Build the file from wherever the settings live, such as the Deployment's env and the ConfigMaps and Secrets it references, a systemd unit's EnvironmentFile, or compose's env_file. There is no sync for uploads: upload again when the settings change.

AWS permissions inside a box

A service's AWS permissions usually are not in its environment variables: AWS hands them to the machine it runs on (an ECS task role). Moving the service into a box leaves that behind, so anything using S3 or SQS fails.

An environment can name a role for its boxes, through OIDC, the same way GitHub Actions and Vercel reach AWS:

1. GET /v1/environments/{env} returns this environment's identity (awsSubject, tenant:<account>:env:<environment>) and awsBoxRoleQuickCreateUrl, a one-click CloudFormation link for the role.
2. Create the role in AWS with the permissions your boxes need, then PUT /v1/environments/{env} with { "awsRoleArn": "<role ARN>", "awsRegion": "<region>" }.
3. Boxes started after that have AWS_CONTAINER_CREDENTIALS_FULL_URI set to the box's own credentials address, the one ECS uses, plus AWS_REGION and AWS_DEFAULT_REGION. AWS SDKs and the CLI pick it up, fetch credentials and refresh them on their own, with no code change. Containers too, when started with docker run --env-file /work/.sbx/env/<service>.env. aws sts get-caller-identity in the box shows assumed-role/<role>/psbx-<box id>.

ParallelSandbox signs a ten-minute identity for the box; the box exchanges it with AWS for credentials that expire in an hour. No long-lived key exists anywhere, and ParallelSandbox holds nothing that can act in your account. Deleting the role or changing its trust policy takes effect immediately, and the role trusts only the environment you named.

To pull images from your own ECR in a box (dev's current image of a service you did not change, say), the role needs ecr:GetAuthorizationToken, and ecr:BatchCheckLayerAvailability, ecr:GetDownloadUrlForLayer and ecr:BatchGetImage on the repositories (the AWS managed policy AmazonEC2ContainerRegistryReadOnly has all four). Then, in the box: aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com, and docker run --env-file /work/.sbx/env/<service>.env … <image>. Without those permissions the login fails with AccessDeniedException … is not authorized to perform: ecr:GetAuthorizationToken.

Use it from a box

sandbox_environments {}
sandbox_start { "name": "refund flow rework", "goal": "Rework the api's refund flow against dev's databases and services; done when a refund made through the api is recorded in dev", "environment": "dev", "services": [{ "name": "api", "port": 8080 }] }

The sandbox_start result gains an environment: reachable lists the private addresses the box can reach, connectorOnline says whether a connector is up (with several connections, whether any of them is), connections[] gives each connection's name, online, sessions, lastSeenAt, connectorVersion and reachable (the addresses that go through it, minus names the box runs itself), and services gives each service's settings files. When some connections are offline, next names them with their addresses; when none is online, it says the connector is offline. sandbox_status returns the same environment, read again on every call, so it shows a connection going offline after the box started.

If the environment has an externalBaseUrl, the box inherits it, and every service you declared starts in external mode: name:port forwards HTTP to externalBaseUrl. Switch the ones you run in the box to box; boxd does not hold their port, so it does not matter whether their process is already running:

sandbox_wire { "id": "<id>", "service": "api", "mode": "box" }

Start the services you changed with their settings:

sandbox_exec { "id": "<id>", "cmd": "cd api && docker build -t api . && docker run -d --name api --env-file /work/.sbx/env/api.env -p 8080:8080 api", "note": "build and start the api with its dev settings" }
sandbox_exec { "id": "<id>", "cmd": "cd api && . /work/.sbx/env/api.sh && go run ./cmd/api", "background": true, "note": "run the api with its dev settings" }

• .env is the docker run --env-file format with values as is; .sh is export KEY='VALUE' for programs you run directly. Multi-line values are only in .sh. To change one value for the box, add -e KEY=value after --env-file; it wins.

• Which settings matter: a service's settings can run to a hundred names. sandbox_start and sandbox_status list, per service, keysCount and notable instead of every name: connection settings point at the environment itself (this is how you find the database variable when it is not DATABASE_URL), mode settings (SERVER_MODE, STAGE, *_BYPASS) hold dev's value, which can turn authentication or checks off, so a test of that path may pass for the wrong reason, and permission settings (admin lists, allowlists) hold dev's own list, not production's. Override a mode with -e or export when the test depends on it. sandbox_environments lists every name.

• A front end usually has its own switch for which backend it calls (CUBELV_ENV=dev, VITE_API_URL, STAGE), and that is in no service's settings unless someone stored the front end as a service of the environment. Read the project's README for how it runs against dev and set those when you start its dev server or build it, or the page you test talks to production.

• For a program you run directly, source the .sh and then override what the box needs, either for that one command or with export:

  . /work/.sbx/env/api.sh && DATABASE_URL="$(psbx-testdb url)" ./bin/backfill
  

  Do not source the .env (set -a; . api.env): its values are not quoted, so one with a space or a quote stops the shell with an error, and one with a $ changes without a word.

• A published version declared with version gets the settings file of the service it was published for, /work/.sbx/env/<service>.env, without any flag of yours (Run a published version).

• docker compose expands $ inside env_file values; if a value contains $, use docker run --env-file, or source .sh and pass variables with environment:.

• Programs and containers in the box keep using the usual host names, no config changes: the names resolve to their addresses inside the box, and boxd carries each connection through ParallelSandbox and your connector.

• When other services call the one you changed by its internal host name (a router forwarding to api.svc.local:8080, say), declare it in services under that name at sandbox_start: [{ "name": "api.svc.local", "port": 8080 }]. port is what callers dial; if your process listens on another port, add it as targetPort, which is required when callers dial port 80, as with an internal load balancer: [{ "name": "internal-lb.svc.local", "port": 80, "targetPort": 8080 }]. Inside the box that name then points at the box instead of your connector, and reachable leaves it out; everything you did not change still goes to your dev. Callers that run on your dev keep reaching your dev's copy; run a caller in the box too if the test needs it. Declared later with sandbox_wire (port for your own process, version for a published version), the name is taken over in place on boxes whose sandbox_status → health.features includes take-over (every box started from 2026-09-25 12:40 UTC): it keeps its address, connections open through the connector are closed, and programs reconnect to the box's copy. On older boxes such a name keeps going to the connector, so declare it at sandbox_start there (Taking over a link or an environment address).

• A changed service started with its settings talks to your real dev database: its migrations and writes land there. For tests, psbx-testdb up <name> starts a clean Postgres 16 in the box and writes its connection to /work/.sbx/testdb/<name>.env (DATABASE_URL, TEST_DATABASE_URL and more, as export lines; --as NAME adds another variable); it listens on 127.0.0.1, so a container needs --network host to reach it. Team setup lists its options. To run a service against a database of its own, start one in a container and override the setting after --env-file (-e DATABASE_URL=…). Team setup has the commands. To read dev's data without risking a write, psbx-ro-psql <service> connects with that service's Postgres setting (the only postgres:// one, or the variable you name), with default_transaction_read_only and a 60-second statement_timeout, and masks the connection string and password in its output: psbx-ro-psql market-data -c 'select count(*) from quotes'. It guards against slips, not against someone who wants to write (SET can undo it). psbx-testdb up --redis starts a Redis for tests the same way (REDIS_URL), and psbx-testdb up --s3 an S3-compatible server (AWS_ENDPOINT_URL, the keys, AWS_REGION and S3_BUCKET).

• When the caller does not use a host name but dials addresses it got from its own registry (a gateway taking worker IPs from Redis, say), declare an address range in services: [{ "name": "172.16.0.0/16", "port": 9090 }]. Connections from the box, containers included, to that range on that port reach your service in the box on its targetPort; other ports are untouched. Private addresses only: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, declared at sandbox_start. Environment addresses inside the range on the same port stop going through the connector.

Team setup walks through a full example: two networks, several changed services, Sentry, and a changed service used from another box.

Troubleshooting

• sandbox_environments: per environment reachable, connectorOnline (true when any connection is up) and connections[], which shows each connection's online, sessions, lastSeenAt and connectorVersion and the addresses it carries. Read connections[] first: an offline office shows there even while connectorOnline is true. sandbox_status → environment.connections[] shows the same for the box's environment. The final check for one network is still to use one of its addresses from a box with a real client (curl, pg_isready, psql and redis-cli are installed in the box; a bare TCP connect succeeds either way, because boxd accepts it first), then read that address in health.privateEndpoints.
• health.privateEndpoints in sandbox_status: for each address, the entry boxd opens for it inside the box (localIp, localPort), open connections, connections opened, failures, and the reason for the last failure.
• /work/.sbx/logs/private-endpoints.log: one line per failed connection.
• sandbox_exec results carry privateEndpointErrors and privateEndpointHint when a connection the command made to an environment address failed: the same reasons as health.privateEndpoints and the log, for that command only, since the program itself only sees its connection reset.
• Slow through the connector: every connection a box makes through it pays at least the round trip in connections[].rttMs (ParallelSandbox to the connector, measured every heartbeat), on top of the path inside your network. Timings measured through it compare with each other as ratios, not with timings taken inside your network.
• 403: the address is no longer listed on any connection of the environment; add it back with PUT /v1/environments/{env}/connections/{id}/endpoints. An address added after the box started is not known to that box at all (the box has no address for its name); start a new box.
• Could not resolve host (no such host, NXDOMAIN) for one of your internal names, such as a private API Gateway <api-id>.execute-api.<region>.amazonaws.com: the name is not listed, and public DNS does not know it. Add it with its port to the connection that can reach it. PUT .../endpoints replaces the whole list, so take the current one from GET /v1/environments/{env} and send it back with the new address; then start a new box.
• 503: the connector of the connection that lists the address is offline, and the message names that connection (the connector "office" of this environment is offline; …); check its log (docker logs parallelsandbox-connector, or the ECS task's log). The client in the box sees its connection accepted and then reset.
• 502: the connector could not reach the target; check DNS, routes and security groups between the connector's machine and that address.
• Errors right after a box thaws: boxd closes connections to your addresses that were open before the freeze, within about 15 seconds of the thaw, so programs see an error instead of a connection that never answers. Database pools usually reconnect on their own; long-lived clients have to retry.

Limits

• TCP only. Addresses are exact host names or IPv4 addresses with a port; wildcards and ranges are not supported.
• At most 100 addresses per connection, and 200 per box across all connections.
• A box gets the environment's addresses, settings, externalBaseUrl and AWS role when it is claimed: addresses added or settings changed later reach new boxes only. Removing an address, a connection or the environment takes effect immediately, for running boxes too.