Self-host Agentlas OS: agent hub on a VPS
Install Agentlas OS v1.2.0 on a Linux VPS: the pinned install, where state lives, how to point it at Ollama, and what an idle agent hub really costs.
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. The pinned v1.2.0 command-line installation below is not a service: its installer does not enable a daemon or open a listening port. The current project also documents a separate desktop app.
That last distinction 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
As recorded on 13 October 2026, the repository was about four months old, with roughly 1,580 stars and 110 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. The 1.2 series kept the pace: it had reached v1.2.62 by 10 October 2026. 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 this often gives you whatever was tagged most recently when the script was last edited.
What you need on the VPS
The requirements are small because idle specialists are files, not processes.
- A Linux VPS. Ubuntu 24.04 is a fine baseline. The installer detects the operating system with
uname -sand takes a non-macOS branch for Linux, so a headless box is supported. curl,tarandgiton the box, plus Python 3.9 or newer, which the pinned installer uses to verify the bundled embedding model.- Outbound HTTPS to
raw.githubusercontent.comandgithub.comfor a normal install. The installer downloads a release archive and checks its SHA-256. The current standalone installer rejectsHEPHAESTUS_SOURCE_DIRwithstandalone_local_source_unverified; offline installation through that variable is no longer supported. - 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 under your home directory, including ~/.local/bin. When a step fails, such as a path that is not writable, it warns and carries on with the rest, then exits non-zero at the end if anything failed. 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 the v1.2.0 installer and read it first. It writes 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/v1.2.0/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.shHEPHAESTUS_REF is the pin. As of 8 November 2026, the script on main uses release_ref="${HEPHAESTUS_REF:-os-v1.2.89}", and the releases page labels Agentlas OS 1.2.89, released today under os-v1.2.89, as Latest. The current installer requires an os-v tag and rejects HEPHAESTUS_REF=v1.2.0 with standalone_channel_tag_invalid. The historical installer above accepts that pin.
The script URL above pins both the installer and the runtime payload to v1.2.0. Current standalone installs use ~/.agentlas/os-runtime and the ~/.agentlas/os-bin/agentlas-os launcher, and no longer install global wrappers or permanently register host plugins and MCP by default. Those defaults differ from the historical installation described below.
The pin covers the install, not what happens afterwards. In v1.2.0, hephaestus commands start a background update check that, when a newer release exists, installs it and repoints ~/.agentlas/runtime/current without asking. The installer disables this for its own run with HEPHAESTUS_AUTO_UPDATE=0, and the same variable is how you keep this historical pin in place. It is added to your shell profile in the next step. Current standalone automatic updates are off by default.
A successful run prints the paths it wrote, including these lines when ~/.local/bin is absent from PATH:
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 PATH warning is the line 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. Add it to ~/.bashrc, turn off the historical background updater at the same time, and confirm:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
echo 'export HEPHAESTUS_AUTO_UPDATE=0' >> ~/.bashrc
source ~/.bashrc
hep-global statushep-global is the original spelling of hephaestus global, and status shows whether each harness instruction file carries the managed router block. That router is off by default, so expect it to report none. If the command 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/1.2.0/holds the runtime itself (the installer drops the leadingvfrom the tag), 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, includinghephaestus,hep-build,hep-network,hep-search,hep-storm,hep-cloudandhep-upload.~/.agentlas/networking/memory/holds the durable memory:playbook-registry.json,playbook-candidates.jsonlandmemory-events.jsonl.~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqliteholds per-agent experience, scoped by owner.<project>/.agentlas/ontology-runtime.sqliteholds per-project state, so it travels with the repository rather than the box.~/.cache/agentlas/pythonholds the Python cache on Linux. macOS uses a different path, which is the branch the installer picks withuname.
The v1.2.0 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.
One thing that leaves the box: in the pinned v1.2.0 release, hep-build sends anonymous build counters by default, without prompts, paths or agent content. Set AGENTLAS_TELEMETRY=0 or DO_NOT_TRACK=1, or put both "telemetry": false and "telemetrySetBy": "user" in ~/.agentlas/networking/config.json, to turn that off. Current standalone telemetry is off by default.
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 the README states that the adapter owns its provider authentication, with the caller supplying their own model and API access. 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 opencodeSubstitute 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 ollamaA successful route returns a JSON decision naming the agent or team it selected, with a receipt_id. If it returns nothing useful, check the context length. The v1.2.0 local-models 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. A harness launched against Ollama still supplies its commands, skills and plugins; a raw Ollama API loop uses the MCP server or the hephaestus route command instead. That is a real reduction in surface for a raw API loop.
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 documentation describes a runner that launches workers for a task, and nothing in it opens a listening port or asks you to enable a service. Between tasks, check for yourself:
pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlasOnce command-triggered workers have exited, the first two commands print nothing on an idle box, because specialists are not resident. The pinned v1.2.0 can leave short-lived, detached update and build-telemetry workers running after a command returns. HEPHAESTUS_AUTO_UPDATE=0 disables its updater; telemetry needs its own opt-out described above. Current standalone update checks and telemetry are off by default. 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 the harness process, whose memory use depends on the harness and workload. If you self-host the weights, the weights are the bill:
The data behind this chart
[
{
"label": "Hosted API model",
"weights_gb": 0
},
{
"label": "gemma3:4b",
"weights_gb": 3.4
},
{
"label": "gemma3:12b",
"weights_gb": 8.2
},
{
"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 harness, plus files and task-scoped runtime processes. 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 pinned installer wrote to ~/.local/bin, which is absent from some fresh shells' PATH. It said so near the end of its output, and the warning scrolled past. Add the export shown above to ~/.bashrc.
Behaviour changes after you rebuild the box. You did not set HEPHAESTUS_REF, so the installer defaulted to whatever tag its script named that day. Pin it, and record the pin next to your other version numbers.
Behaviour changes without a rebuild. In the pinned v1.2.0, the background updater can install a newer release and move ~/.agentlas/runtime/current to it. Check what current points at, and set HEPHAESTUS_AUTO_UPDATE=0 in the environment your harness runs in, not only in an interactive shell. Current standalone automatic updates are off by default.
Routing picks the wrong specialist on a local model. Check whether 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. Ollama defaults to 4k below 24 GiB VRAM, 32k from 24 to below 48 GiB, and 256k at 48 GiB or more, so the smaller configurations need an explicit increase.
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 pinned script detects and configures every harness it finds, writing to ~/.claude/, ~/.codex/, ~/.gemini/, ~/.cursor/ and more, and it edits config files that already exist, such as ~/.codex/config.toml, keeping a backup beside the original. 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 project this young with automated releases, sometimes several a day, is not something to put under a production workload. The architecture is genuinely interesting, the license is Apache-2.0, and all of its state lives in files you can back up. Removal is less tidy than that suggests: the v1.2.0 README documents no uninstall, the pinned installer writes across multiple locations in your home directory and edits existing harness configs, and hephaestus global remove takes out just the optional router block. Those facts make it cheap to try on a disposable box and expensive to depend on.
A sensible position for now: pin v1.2.0 using its tagged installer, set HEPHAESTUS_AUTO_UPDATE=0 so this historical pin holds, 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?
The pinned v1.2.0 command-line installation does not enable a daemon or open a listening port. The installer writes a runtime under ~/.agentlas/runtime/ and command wrappers into ~/.local/bin, and the Hephaestus Network runs when a task launches it rather than as a background service. Once command-triggered workers have exited, pgrep -af hephaestus prints nothing on an idle box. The pinned release can launch short-lived update and build-telemetry workers: HEPHAESTUS_AUTO_UPDATE=0 disables its updater, while AGENTLAS_TELEMETRY=0 or DO_NOT_TRACK=1 disables telemetry. Current standalone update checks and telemetry are off by default. 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. Tasks and short-lived background workers consume memory; parked specialists do not.
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 fetching the installer from the v1.2.0 tag and setting HEPHAESTUS_REF=v1.2.0 as shown above. As of 8 November 2026, the script's default on main is release_ref="${HEPHAESTUS_REF:-os-v1.2.89}", and Agentlas OS 1.2.89 is the latest release, published today under os-v1.2.89. That current installer accepts only os-v version tags and rejects the old v1.2.0 pin. 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. Also set HEPHAESTUS_AUTO_UPDATE=0 for the historical v1.2.0 runtime, because its updater otherwise installs newer releases in the background and the pin quietly stops holding. Current standalone automatic updates are off by default.