Skip to Content
Agent computeWhat your agent runs as
Raw

What your Aetherfy agent runs as

Every Aetherfy agent runs as an unprivileged user, on every start of its machine, whether it is a service or a job, on a standard runtime or in a custom container. Aetherfy’s supervisor starts as root, prepares the machine, and only then starts your process as that user. On a standard runtime it is a user of Aetherfy’s own. In a custom container it is the user your image ends on, unless that is root (or cannot be found in the image), in which case it is Aetherfy’s own user. This page is the contract that follows from it.

What your Aetherfy agent can and cannot do as an unprivileged user

Your agentSupported
Read and write its app directory, its home directory and /tmpYes, on the standard runtimes. A custom container writes what its USER owns and the paths it lists in writable_paths
Install packages for itself at run time with pip install, npm install or bun addYes, see below
Cache downloads, including headless-browser downloads such as Playwright and Puppeteer, under its home directoryYes, the cache directory is in the home directory
Call the public internet, Aetherfy’s own APIs and the Aetherfy vector APIYes
Install system packages with aptNo
Change file ownership with chown, or run as rootNo, and a setuid program does not give the agent more rights either
Listen on a port below 1024No. A service’s server uses the port it is told, 8080
Reach the machines of other agents over a private network, or look up .internal namesNo, see below
Change the machine’s network rules or its name resolutionNo

Where your Aetherfy agent can write

LocationStandard runtimes (python3.*, node*, bun)Custom container (runtime: dockerfile)
The app directory, /appWritable, including creating new files and foldersOnly the paths in writable_paths
The home directory, HOMEWritableWritable: /home/agent, unless your image sets a HOME of its own
The cache directory, XDG_CACHE_HOME, inside the home directoryWritableWritable
/tmpWritableWritable, unless your image changed its permissions
Everywhere elseNot writableOnly the paths in writable_paths

A custom container’s files belong to whoever your Dockerfile made them belong to. When your image ends on a non-root USER, your command runs as that user and its own files and home directory work as they do anywhere. For anything it writes that it does not own, list the path in writable_paths in aetherfy.yaml: Aetherfy hands exactly those paths to the agent’s user before it starts. An image that runs as root gets Aetherfy’s own unprivileged user instead, which owns nothing in your image, so a file that only root (or another user) can read is not readable by it: make it readable by everyone or use a secret.

Installing packages while your Aetherfy agent runs

Installs your own code runs go to the agent’s home directory or to its app directory, never to system locations:

RuntimeWhat worksWhere it lands
Python, with requirements.txtpip installA user-level install in the home directory, which Python finds on its own
Python, with uv.lockuv pip installThe project’s virtual environment in the app directory
Node.js and Bunnpm install, bun addnode_modules in the app directory
Node.jsnpm install --globalA user-level prefix in the home directory, on PATH

An install at run time lasts until the machine is stopped and started again, which begins from the image, so put what your agent always needs in requirements.txt, package.json or pyproject.toml.

The Aetherfy SDK your agent comes with

Every standard runtime comes with the Aetherfy SDK, aetherfy-vectors, already installed: aetherfy_vectors, aetherfy_agent and aetherfy_memory in Python, and aetherfy-vectors and aetherfy-vectors/agent in Node.js and Bun. Your agent imports them without listing the SDK among its dependencies.

Aetherfy updates the installed version after each SDK release, and your agent’s next deploy picks it up.

If your dependencies include aetherfy-vectors, at any version, your agent gets that version instead, and Aetherfy installs nothing over it. Leave the SDK out unless you need a specific version: you then get fixes and new features with your next deploy, with nothing to update.

A custom container (runtime: dockerfile) does not come with the SDK: see installing the Aetherfy SDK in a custom container.

The Aetherfy network your agent can reach

Your agent has no access to a private network and no .internal DNS. It reaches the public internet and Aetherfy’s public addresses, and it reaches the Aetherfy vector API at the address in AETHERFY_VECTORS_URL. Names under .internal and reverse lookups are refused, so a lookup of one fails the same way whatever the name is, and an address on the compute plane’s private network other than the vector API’s is not reachable. Other machines on that private network cannot open a connection to your agent either; callers reach a service through its public address.

A service’s public address is served only through Aetherfy’s edge. A request sent straight to its machine, without going through the edge, is refused.

When Aetherfy cannot set up your agent’s isolation

Aetherfy sets all of this up on every start of the machine, before your process exists. If it cannot, it does not start your agent, and it never serves an agent without its isolation. That is the platform’s problem and not caused by your code:

Where you see itWhat you see
A deployment of a serviceThe deployment ends failed, and its error_message is: “The platform could not set up the isolation of this agent, so it was not started. This is not caused by your code, and no agent is ever served without its isolation. Deploy the agent again; if it keeps happening, contact support.”
The agent, when no earlier version is servingThe agent is failed, with failure_code isolation_setup_failed and the same sentence as failure_message
A run of a jobThe run ends failed with the same sentence, and your code did not execute

Deploy the agent again. Aetherfy is told when this happens; if it keeps happening for the same agent, contact support with the agent’s name. A machine that could not isolate its agent does not stay up: it stays long enough for the failure to be read (about ten minutes), stops itself, and a later request or deploy starts it again from scratch and tries the isolation again.

Last updated on