Self-host Agentlas OS: agent hub on a VPS

What Agentlas OS actually is

Agentlas OS is an open source agent runtime that keeps specialist agents on disk as packages and assembles a temporary orchestrator for each task. You self-host it by installing it into your own user account on a Linux VPS. It is not a service. There is no daemon, no listening port, no web interface, and no container image in the repository.

That last sentence decides everything else on this page. Most multi-agent systems run a supervisor process that stays up and holds the agents. Agentlas inverts that: the specialists are files at rest, and the orchestrator exists only while a task runs. The practical result is that an idle hub costs you disk, not memory.

The project calls its open core Hephaestus, and that name is what you will see in commands, paths and environment variables. The repository is agentlas-ai/Agentlas-OS, licensed Apache-2.0, and written mostly in Python.

How early is this project, honestly

The repository was created on 4 June 2026. As of 12 August 2026 it is about ten weeks old, with roughly 1,150 stars and 112 forks. That is young for something you point at real work.

The release cadence matters more than the age. Version v1.1.103 was published on 8 August 2026, and v1.2.0 landed on 12 August 2026. That is over a hundred tagged releases in the 1.1 series, several on some days, published by automation. A project moving at that speed will change behaviour under you between a Tuesday and a Thursday.

So pin the release. The installer reads an environment variable for this, and the whole guide below uses it. An unpinned install of a project shipping several times a day gives you whatever happened to be on main that hour.

What you need on the VPS

The requirements are small because nothing runs in the background.

• A Linux VPS. Ubuntu 24.04 is a fine baseline. The installer detects the operating system with uname -s and takes a non-macOS branch for Linux, so a headless box is supported.
• curl, tar and git on the box, plus a working Python interpreter.
• Outbound HTTPS to raw.githubusercontent.com and github.com. The installer downloads a release archive and checks its SHA-256, so a box with no outbound reach cannot install this.
• A host harness, which is the coding agent that actually talks to a model. Claude Code, Codex, opencode, goose and Hermes are all supported adapters.

You do not need root. The installer writes only to your home directory and to ~/.local/bin, and it warns rather than aborting when a path is not writable. If you are still choosing the box itself, running a coding agent on a VPS covers the base image and access setup this sits on top of.

Install the pinned release

The upstream README documents a single line that pipes a script from main straight into bash. Download it and read it first. It writes into your shell configuration and into every agent harness it finds, so it is worth ten seconds of your attention.

curl -fsSL -o install-all-runtimes.sh \
  https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.sh

HEPHAESTUS_REF is the pin. Inside the script the line is version="${HEPHAESTUS_REF:-v1.2.0}", so leaving it unset happens to give you v1.2.0 today and something else next week. Set it explicitly and your rebuild in October installs what you tested in August.

One honest limit: the script URL above tracks main, while HEPHAESTUS_REF pins the runtime payload the script downloads. Those are two different things. To pin both, fetch the script from the tag instead of main by replacing main with v1.2.0 in that URL.

A successful run prints the paths it wrote, including these two lines:

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)

That second line is the one people skip. On a fresh Ubuntu box ~/.local/bin is often absent from PATH, so every hep-* command fails with command not found even though the install succeeded. Fix it and confirm:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hep-global status

hep-global status reports what the global router installed and which harnesses it detected. If it runs at all, your PATH is correct.

Where the state lives

Everything is a file under your home directory, which makes backup and migration simple.

• ~/.agentlas/runtime/v1.2.0/ holds the runtime itself, with ~/.agentlas/runtime/current/ as a symlink to the active version. Two pinned versions can sit side by side.
• ~/.local/bin/ holds the shell wrappers: hephaestus, hep-build, hep-network, hep-search, hep-storm, hep-cloud and hep-upload.
• ~/.agentlas/networking/memory/ holds the durable memory: playbook-registry.json, playbook-candidates.jsonl and memory-events.jsonl.
• ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite holds per-agent experience, scoped by owner.
• <project>/.agentlas/ontology-runtime.sqlite holds per-project state, so it travels with the repository rather than the box.
• ~/.cache/agentlas/python holds the Python cache on Linux. macOS uses a different path, which is the branch the installer picks with uname.

The memory documentation is explicit that secrets, raw credentials and full transcripts must not go into any memory scope. Credential values stay in gitignored local files, and memory records only names and paths. Back up ~/.agentlas and your project .agentlas directories and you can rebuild on a new VPS.

Which model backends it can point at

Here is the detail that reframes the whole setup: Agentlas does not call a model API. The host harness does.

The architecture document describes runtime adapters that translate one core into each harness, and states that the host runtime owns model credentials. Agentlas contributes two surfaces that a harness picks up: an AgentSkills file and an MCP (model context protocol) server that speaks over stdio. So the question "which models does Agentlas support" is really "which models does your harness support", and the answer is anything Claude Code, Codex, opencode, goose or Hermes can reach.

Registering the MCP server looks like this in a Codex-style TOML config:

[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]

The same server is registered into ~/.cursor/mcp.json, ~/.config/goose/config.yaml and the other harness configs automatically during install. If you are wiring several of these into one box, running MCP servers on a VPS covers the stdio and process model in more depth.

Point it at a self-hosted Ollama endpoint

Because the harness owns the model connection, pointing Agentlas at local models means pointing your harness at Ollama. Ollama added a launch subcommand in v0.15 for exactly this, and it is still shipping in v0.32.9 as of 11 August 2026. It configures an existing harness against local models with no environment variables to set:

ollama pull qwen3-coder:30b
ollama launch opencode

Substitute claude, codex or droid for opencode depending on the harness you installed. Then route a request through the local runtime:

~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollama

A successful route returns a JSON decision naming the agent or team it selected, with a receipt_id. If it returns nothing useful, the usual cause is context length. The Agentlas documentation asks for a model with at least 64k context for routing-heavy sessions and names qwen3-coder, gemma3 and deepseek-r1 as examples. Ollama's own guidance for coding tools is the same 64k floor. Routing decisions carry the agent inventory in the prompt, so a 8k or 32k context model truncates the inventory and picks badly.

One caveat the tagline will not tell you. Ollama, Gemma and DeepSeek have no plugin or command system of their own, so the /agentlas slash commands do not exist there. On a local-model setup you drive the system through the MCP server and the hephaestus route command instead. That is a real reduction in surface, and it is the honest trade for keeping the weights on your own box.

What a hub of idle specialists costs in RAM

Nothing. That is the whole answer, and you can prove it rather than trust it.

Borrowed hub specialists arrive as package artifacts, not processes. A specialist is an agent.md plus a .agentlas/ directory of JSON: routing-card.json for triggers and capabilities, memory-map.json for write boundaries, mode-map.json for whether it runs solo or as a team. The Hephaestus Network is described as an in-process scheduler with no background service. Between tasks, check for yourself:

pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlas

The first two commands print nothing on an idle box, because nothing is resident. The third prints the only cost a parked hub imposes on you, which is disk, and it grows with the number of specialists you keep plus the bundled embedding model the runtime ships.

So the memory question is entirely a question about the burst, and the burst is your harness plus your model backend. If the harness talks to a hosted API, the resident cost is one process of a few hundred megabytes. If you self-host the weights, the weights are the bill:

[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.3
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.1
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

Those are the published download sizes from Ollama's model library, not measurements from a benchmark run, and the KV cache for a 64k context sits on top of every figure above zero. The model the Agentlas docs name first, qwen3-coder:30b, needs 19 GB of weights before context, and even the 27B Gemma variant asks for 17 GB. Against those numbers, the Agentlas layer itself does not appear in the budget.

How this compares to running one harness

Run one harness against a hosted API and your VPS carries one process. Add Agentlas and it carries the same one process, plus files. The orchestrator is not an extra long-lived program, it is a larger prompt assembled from the packages on disk and then discarded.

The cost that does move is context, not memory. An orchestrator that pulls in several specialist cards and their routing metadata spends more tokens per task than a bare harness, and on a hosted API that is money rather than RAM. On local weights it is time, because a longer prompt means a longer prefill on CPU or a busier GPU.

This is why the sizing advice for a box like this follows the model decision and not the agent framework. Sizing RAM and CPU for a coding agent VPS works through that in detail, and the conclusion holds here: pick the plan for the backend you intend to run, then add a couple of gigabytes of headroom for the harness. If you want the always-on supervisor design for comparison instead, the Omnigent multi-agent harness keeps its coordinator resident, which is the opposite trade and shows up directly in idle memory.

Failure modes and the strings you will see

hep-build: command not found right after a clean install. The installer wrote to ~/.local/bin, which is not on PATH on a default Ubuntu image. It said so in its final line and the line scrolled past. Add the export shown above.

Behaviour changes after you rebuild the box. You did not set HEPHAESTUS_REF, so the installer defaulted to whatever tag was current that day. Pin it, and record the pin next to your other version numbers.

Routing picks the wrong specialist on a local model. The model's context window is too small for the agent inventory. Move to a model with 64k or more and set Ollama's context length to match, since the default is lower than the coding tools want.

ollama launch is not recognised. The subcommand arrived in Ollama v0.15. Older packages from a distribution repository predate it, so install a current Ollama.

The install writes into harnesses you did not expect. The script detects and configures every harness it finds, writing to ~/.claude/, ~/.codex/, ~/.gemini/, ~/.cursor/ and more. On a shared build box, read the script before running it and know which of those directories you care about.

Should you run this yet

A ten week old project with automated releases several times a day is not something to put under a production workload. The architecture is genuinely interesting, the license is Apache-2.0, and the file-based design means uninstalling is deleting two directories. Those facts make it cheap to try and expensive to depend on.

A sensible position for now: pin v1.2.0, run it on a box you can rebuild, keep ~/.agentlas in your backups, and re-read the changelog before you move the pin. For a wider survey of what else is in this space and how mature each option is, the roundup of self-hosted AI agents is the better starting point, and self-hosting a Hermes agent on a VPS covers one of the harnesses Agentlas adapts to.

FAQ

Does Agentlas OS run as a server on my VPS?

No. There is no daemon, no listening port and no container image in the repository. The installer writes a runtime under ~/.agentlas/runtime/ and command wrappers into ~/.local/bin, and the Hephaestus Network is an in-process scheduler rather than a background service. You can confirm this on an idle box: pgrep -af hephaestus prints nothing, and there is no systemd unit to enable. Self-hosting here means the code and the state are on your machine, not that a service is listening.

How much RAM does a hub of idle specialists use?

None, because idle specialists are not processes. A specialist is an agent.md file plus a .agentlas/ directory holding routing-card.json, memory-map.json and similar metadata, so a parked hub costs disk. Measure it with du -sh ~/.agentlas. Memory is consumed only while a task runs, and what consumes it is your harness process and your model backend, not the Agentlas layer.

Which models can I use, and can I point it at my own Ollama?

Agentlas does not call model APIs itself. The host harness owns the credentials and the connection, so the supported models are whatever your harness supports. For local weights, run ollama launch opencode (substituting claude, codex or droid), which configures the harness against your Ollama server with no environment variables. Use a model with at least 64k context, such as qwen3-coder or gemma3, because routing prompts carry the agent inventory and truncate badly on smaller windows.

Which version should I install, and why does pinning matter here?

Install v1.2.0, the tagged release current on 12 August 2026, by setting HEPHAESTUS_REF=v1.2.0 before running the installer. The script's own default is version="${HEPHAESTUS_REF:-v1.2.0}", which tracks whatever the maintainers tag next. Pinning matters more than usual because the project published over a hundred releases in its 1.1 series, several on some days, so an unpinned rebuild weeks later will not give you the system you tested.