Access Control

Nullspace preview ingress is designed around short-lived signed URLs and create-time network policy. Use get_host_info(port) for signed HTTP and WebSocket URLs, and use network on machine creation for public traffic and outbound rules.

Signed host URLs

from nullspace import Machine

with Machine.create(template="base") as machine:
    info = machine.get_host_info(8080)
    print(info.host)
    print(info.url)
    print(info.websocket_url)
    print(info.access_token_expires_at)

import { Machine } from "nullspace";

const machine = await Machine.create({ template: "base" });
const info = await machine.getHost(8080);
console.log(info.host);
console.log(info.url);
console.log(info.websocketUrl);
console.log(info.accessTokenExpiresAt);

nullspace machine host mch_123 8080 --json

curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/host" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "port": 8080 }'

Field	Meaning
`host`	Bare host mapping for a machine port.
`url`	Signed HTTP URL when public edge ingress is active.
`websocket_url`	Signed WebSocket URL for the same exposed port.
`access_token_expires_at`	Expiration time for signed edge URLs.
`access_token_transport`	Token transport; currently `query` for signed URLs.

Signed URLs are bearer credentials. Anyone with the URL can use it until it expires, subject to the machine network policy.

Require a traffic token

Set network.allow_public_traffic to False when preview URLs should require a private traffic credential in addition to any signed edge URL token.

machine = Machine.create(
    template="base",
    network={"allow_public_traffic": False},
)

token = machine.traffic_access_token
url = machine.get_url(8080)

curl -fsS \
  -H "x-nullspace-traffic-access-token: ${NULLSPACE_TRAFFIC_ACCESS_TOKEN}" \
  "${NULLSPACE_PUBLIC_URL}"

The traffic_access_token is returned only at create time. Store it like an application secret if you need to make later requests through private public URLs.

Edge-owned ingress uses signed edge_token URLs returned by get_host_info(). When allow_public_traffic is false, send x-nullspace-traffic-access-token with that SDK-returned URL. Treat both the URL token and traffic token as secrets.

Custom preview proxy tokens

Use machine.create_preview_proxy_target(port) when your application proxy should hold the Nullspace credential instead of sending signed URLs to browsers. The response includes marker-only upstream URLs, x-nullspace-preview-proxy-token, HTTP/WebSocket-specific token values, and the forwarded headers your proxy should preserve. If allow_public_traffic is false, the proxy target response reports that a traffic token is required and returns the traffic header name. It does not return the private traffic token value; use the traffic_access_token from machine creation as a separate upstream header.

Mask the upstream Host header

Some development servers route by Host. Use mask_request_host to override the Host header sent to the machine service.

machine = Machine.create(
    template="base",
    network={
        "mask_request_host": "localhost:${PORT}",
    },
)

${PORT} is substituted with the exposed machine port for each proxied request.

Control outbound access

Disable all outbound network access with internet_access=False, or use CIDR-based allow/deny rules when the deployment supports network policy.

machine = Machine.create(
    template="base",
    internet_access=True,
    network={
        "deny_out": ["0.0.0.0/0"],
        "allow_out": ["10.0.0.0/8"],
    },
)

Setting	Effect
`internet_access=False`	No machine network connectivity.
`deny_out`	IPv4 CIDRs to block for outbound traffic.
`allow_out`	IPv4 CIDRs to allow when paired with broad deny rules.

WebSockets and SSH relay

Signed WebSocket URLs use the same public edge and access controls as signed HTTP URLs. Missing edge tokens return 401, expired tokens return 410, and tokens scoped to the wrong machine, port, or transport return 401. Default SSH access uses the certificate-backed relay, not a signed edge websocket_url. Use nullspace ssh to mint a short-lived OpenSSH user certificate for a local public key and connect through the relay:

nullspace ssh mch_123
nullspace machine ssh-access mch_123 --print-command

The legacy port-22 WebSocket proxy fallback treats the signed websocket_url as a bearer credential, so prefer the relay whenever it is available.

Embedding and browser headers

Direct preview cookies are SameSite=Lax and are intended for top-level browser navigation, not third-party iframe embedding. Machine X-Frame-Options and Content-Security-Policy headers pass through to the browser; Nullspace preview edge does not add an iframe-safe frame policy for direct preview links. Preview CORS remains owned by the machine app or customer-run proxy. No preview skip-warning, disable-CORS, or skip-activity header is supported by Nullspace edge in the current launch.

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Signed host URLs

Require a traffic token

Custom preview proxy tokens

Mask the upstream Host header

Control outbound access

WebSockets and SSH relay

Embedding and browser headers

​Signed host URLs

​Require a traffic token

​Custom preview proxy tokens

​Mask the upstream Host header

​Control outbound access

​WebSockets and SSH relay

​Embedding and browser headers

​Related

Signed host URLs

Require a traffic token

Custom preview proxy tokens

Mask the upstream Host header

Control outbound access

WebSockets and SSH relay

Embedding and browser headers

Related