---
slug: agents/runtime-environment
title: What your agent runs as
kind: reference
surface: agents
summary: What an Aetherfy agent's process may do on its machine, including the unprivileged user it runs as, where it can write, how pip, npm and bun installs work, the Aetherfy SDK it comes with, why it has no private network, and what happens when that isolation cannot be set up.
sources:
  - aetherfy-control-plane:supervisor/edge_proof.go
  - aetherfy-control-plane:supervisor/isolation.go
  - aetherfy-control-plane:supervisor/isolation_dns.go
  - aetherfy-control-plane:supervisor/isolation_linux.go
  - aetherfy-control-plane:supervisor/agent_exec_linux.go
  - aetherfy-control-plane:supervisor/isolation_failed.go
  - aetherfy-control-plane:orchestrator/image_generator.py
  - aetherfy-control-plane:orchestrator/fly_builder.py
  - aetherfy-control-plane:shared/agent_failure_codes.py
  - aetherfy-control-plane:shared/config_parser.py
  - aetherfy-control-plane:shared/isolation_alert.py
  - aetherfy-control-plane:workers/deploy_worker.py
---

# 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`](/agents/aetherfy-yaml) |
| 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`](/agents/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](/agents/dockerfile#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.
