Sandboxing and tenancy

Node code runs in an isolated container with no direct access to the platform. Everything a node does beyond pure computation — logging, reading secrets, using agent memory, inspecting the running flow — goes through the sidecar, and the sidecar enforces tenant isolation. You never write isolation code yourself, and node code cannot opt out of it. This page explains the boundary: how the sandbox works, what node code can and cannot do, and which guarantees you can build on.

How node code is sandboxed#

Every published package runs as two containers side by side in one auto-scaling service:

• user-node — the image built from your package. It runs the generated service wrapper around your handler functions and listens on a Unix socket at /tmp/axiom.sock, on a volume shared only with its sidecar.
• sidecar — the platform-owned proxy. It is the only container that receives execution traffic, and it relays each invocation to the user-node over the shared socket.

Node code has no platform endpoint to call. All platform capabilities reach node code exclusively through ax on AxiomContext: the sidecar relays every ax.log, ax.secrets, and ax.agent.memory call on the node's behalf, and there is no separate address a node can dial to reach the platform directly.

Each invocation delivers exactly this to your handler: the serialized input message, the execution ID, the flow ID, the tenant identity, a variables map holding resolved flow config values and secrets, and a read-only structural view of the running flow (ax.reflection.flow). Nothing else about the platform is visible. Log lines written with ax.log travel back through the same sidecar channel and are stamped with the execution ID and trace context, so they are searchable per execution in production.

The variables map is for flow config values and secrets only — it is not working memory or agent state. Within one execution, state belongs in your typed messages; across executions, use agent memory (see Agent memory).

What node code can do#

A node handler is a plain function: it receives AxiomContext (ax) and a typed input message, and returns a typed output message. Through ax it can:

• Log — ax.log.debug/info/warn/error, structured, per invocation.
• Read secrets — ax.secrets.get(name) returns the plaintext value of any secret the calling tenant has registered, plus a found flag.
• Use agent memory — ax.agent.memory, durable across executions, scoped to the flow and tenant.
• Inspect the running flow — ax.reflection.flow exposes the nodes, edges, and current position, read-only.
• Mutate the running flow — ax.mutation.flow.add_node and add_edge, available only to nodes declared mutation_capable: true in axiom.yaml; every mutation is validated by the platform.

Node code can also make ordinary outbound network calls. Calling an external API — an LLM provider, a database you host — is the normal use of ax.secrets:

# nodes/call_model.py — scaffolded by:
#   axiom create message Prompt --fields "text:string"
#   axiom create message Reply --fields "text:string"
#   axiom create node CallModel --input Prompt --output Reply
from gen.messages_pb2 import Prompt, Reply
from gen.axiom_context import AxiomContext


def call_model(ax: AxiomContext, input: Prompt) -> Reply:
    api_key, ok = ax.secrets.get("OPENAI_KEY")
    if not ok:
        ax.log.error("secret not registered", name="OPENAI_KEY")
        return Reply()
    ax.log.info("calling model", prompt_chars=len(input.text))
    # Use api_key with any HTTP client here — outbound calls are allowed.
    return Reply()

What node code cannot do#

• Call platform services directly. No platform service address is exposed to the node container. Every platform capability — logging, secrets, memory — is accessed through ax. Node code that attempts to dial platform endpoints directly will not reach them.
• Choose or forge its tenant. The tenant and flow identity used for memory access are fixed on the sidecar when the package is deployed — they live in the sidecar container, not yours. The memory proxy overwrites the tenant and flow fields on every memory call, so whatever values node code puts there are ignored.
• Read another tenant's secrets. The platform resolves secrets for the tenant invoking the flow before any node code runs; the variables map a node receives only ever contains that tenant's secrets.
• See engine internals. Flow reflection is a read-only structural mirror; compiled adapters and engine-internal types are not exposed. When the platform rejects a mutation, the node sees only a human-readable error message — structured engine error codes never cross the boundary.
• Mutate a flow that does not allow it. ax.mutation.flow calls are buffered and validated by the platform after the handler returns; they are accepted only when the compiled flow contains a node declared mutation_capable: true, and every accepted mutation is type-checked.

How tenant isolation is enforced#

Tenant isolation happens at three checkpoints, none of them in node code:

1. At the platform edge. Every invocation is authenticated, and the tenant identity is resolved from the caller's credentials before any node code runs (see Create and manage API keys). That identity travels with the execution through every hop.
2. At secret resolution. When an execution starts, the platform fetches the calling tenant's secrets — stored encrypted at rest — and injects the plaintext values into the invocation's variables map. A node can only read what was injected for its caller's tenant (see Manage secrets in a flow).
3. At the sidecar. The sidecar's memory proxy stamps the deploy-time tenant and flow identity onto every memory read and write, discarding anything node code supplied. Agent memory therefore cannot cross tenant boundaries even if a node tries.

Because enforcement lives in the platform and the sidecar, a bug in node code — yours or a marketplace package's — cannot widen its own access.

What you can rely on, and what you own#

You can rely on:

• Secrets stored on the Secrets page of the console (/console/secrets) are encrypted at rest and readable only by executions invoked under your tenant.
• Agent memory is isolated per tenant and scoped per flow — no other tenant, and no other flow, reads your flow's memory.
• One tenant's executions never observe another tenant's payloads, secrets, or memory.
• New platform capabilities arrive as new properties on ax — node function signatures never change when the platform grows.

You still own:

• Where your data goes. The sandbox does not restrict outbound network calls; what a node sends to external services is your code's responsibility.
• Secret hygiene in your own code. ax.secrets.get returns the plaintext value — do not write it to ax.log or copy it into an output message.
• Your dependencies. Third-party libraries in your package run inside your node container with the same access your code has.