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 agent | Supported |
|---|---|
Read and write its app directory, its home directory and /tmp | Yes, 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 add | Yes, see below |
| Cache downloads, including headless-browser downloads such as Playwright and Puppeteer, under its home directory | Yes, the cache directory is in the home directory |
| Call the public internet, Aetherfy’s own APIs and the Aetherfy vector API | Yes |
Install system packages with apt | No |
Change file ownership with chown, or run as root | No, and a setuid program does not give the agent more rights either |
| Listen on a port below 1024 | No. 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 names | No, see below |
| Change the machine’s network rules or its name resolution | No |
Where your Aetherfy agent can write
| Location | Standard runtimes (python3.*, node*, bun) | Custom container (runtime: dockerfile) |
|---|---|---|
The app directory, /app | Writable, including creating new files and folders | Only the paths in writable_paths |
The home directory, HOME | Writable | Writable: /home/agent, unless your image sets a HOME of its own |
The cache directory, XDG_CACHE_HOME, inside the home directory | Writable | Writable |
/tmp | Writable | Writable, unless your image changed its permissions |
| Everywhere else | Not writable | Only 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:
| Runtime | What works | Where it lands |
|---|---|---|
Python, with requirements.txt | pip install | A user-level install in the home directory, which Python finds on its own |
Python, with uv.lock | uv pip install | The project’s virtual environment in the app directory |
| Node.js and Bun | npm install, bun add | node_modules in the app directory |
| Node.js | npm install --global | A 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 it | What you see |
|---|---|
A deployment of a service | The 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 serving | The agent is failed, with failure_code isolation_setup_failed and the same sentence as failure_message |
A run of a job | The 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.