How to self-host Agentlas OS for VPS with Ollama

Wetín Agentlas OS really be

Agentlas OS na open source agent runtime wey dey keep specialist agents for disk as packages, then e dey assemble temporary orchestrator for each task. You fit self-host am by installing am inside your own user account for Linux VPS. E no be service. No daemon dey, no listening port dey, no web interface dey, and no container image dey for the repository.

That last sentence determine everything else for this page. Most multi-agent systems dey run supervisor process wey stay up and hold the agents. Agentlas turn this arrangement around: the specialists na files wey dey rest for disk, while the orchestrator dey exist only when task dey run. The practical result be say idle hub dey cost disk space, not memory.

The project dey call its open core Hephaestus, and na that name you go see for commands, paths, and environment variables. The repository na agentlas-ai/Agentlas-OS, e get Apache-2.0 license, and dem write am mostly for Python.

How early this project dey, honestly

Dem create the repository on 4 June 2026. As of 12 August 2026, e don dey around ten weeks, with about 1,150 stars and 112 forks. This one still young for something wey you wan use for real work.

The release cadence matter pass the age. Dem publish version v1.1.103 on 8 August 2026, and v1.2.0 land on 12 August 2026. That one mean say over hundred tagged releases dey for the 1.1 series, with some days getting several releases, all published by automation. Project wey dey move that fast fit change how e behave between Tuesday and Thursday.

So pin the release. The installer dey read environment variable for this, and the guide below use am throughout. If you install the project without pinning am, you go get whatever dey on main for that hour.

Wetin you need for the VPS

The requirements small because nothing dey run for background.

• A Linux VPS. Ubuntu 24.04 na good baseline. The installer dey detect the operating system with uname -s and e dey use non-macOS branch for Linux, so headless box dey supported.
• curl, tar and git for the box, plus working Python interpreter.
• Outbound HTTPS to raw.githubusercontent.com and github.com. The installer dey download release archive and check the SHA-256, so box wey no get outbound access no fit install this.
• A host harness, wey be the coding agent wey dey actually talk to model. Claude Code, Codex, opencode, goose and Hermes all get supported adapters.

You no need root. The installer dey write only to your home directory and ~/.local/bin, and e dey warn instead of abort when path no writable. If you never choose the box itself, run coding agent for VPS dey explain the base image and access setup wey this one dey build on.

Install the pinned release

The upstream README dey document one line wey pipe script from main straight into bash. Download am and read am first. E dey write into your shell configuration and every agent harness wey e find, so e worth make you use ten seconds check am.

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 na the pin. Inside the script, the line na version="${HEPHAESTUS_REF:-v1.2.0}", so if you leave am unset, e go give you v1.2.0 today and another version next week. Set am explicitly, then your rebuild for October go install wetin you test for August.

One honest limit: the script URL above dey track main, while HEPHAESTUS_REF dey pin the runtime payload wey the script download. Dem be two different things. To pin both, fetch the script from the tag instead of main by replacing main with v1.2.0 for that URL.

If the run succeed, e go print the paths wey e write, 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)

Na that second line people dey skip. For fresh Ubuntu box, ~/.local/bin often no dey inside PATH, so every hep-* command go fail with command not found even though the install succeed. Fix am and confirm:

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

hep-global status reports wetin the global router install and which harnesses e detect. If e run at all, your PATH correct.

State dey live for where

Everything na file inside your home directory, so backup and migration dey simple.

• ~/.agentlas/runtime/v1.2.0/ dey hold the runtime itself, with ~/.agentlas/runtime/current/ as symlink to the active version. Two pinned versions fit dey side by side.
• ~/.local/bin/ dey hold the shell wrappers: hephaestus, hep-build, hep-network, hep-search, hep-storm, hep-cloud and hep-upload.
• ~/.agentlas/networking/memory/ dey hold the durable memory: playbook-registry.json, playbook-candidates.jsonl and memory-events.jsonl.
• ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite dey hold experience for each agent, based on the owner.
• <project>/.agentlas/ontology-runtime.sqlite dey hold state for each project, so e dey move with the repository instead of the box.
• ~/.cache/agentlas/python dey hold the Python cache for Linux. macOS dey use another path, and na the branch wey installer dey choose with uname.

The memory documentation talk am clearly say secrets, raw credentials and full transcripts no suppose enter any memory scope. Credential values dey remain for local files wey gitignore dey exclude, while memory records only names and paths. Back up ~/.agentlas and your project .agentlas directories, and you fit rebuild everything for a new VPS.

Wich model backend e fit point to

Here be the detail wey dey change how you see the whole setup: Agentlas no dey call model API. Na the host harness dey do am.

The architecture document describe runtime adapters wey dey translate one core go each harness, and e talk say na the host runtime dey handle model credentials. Agentlas contribute two surfaces wey harness fit pick up: AgentSkills file and MCP (model context protocol) server wey dey communicate over stdio. So the question “which models Agentlas support” really mean “which models your harness support”, and the answer be anything wey Claude Code, Codex, opencode, goose or Hermes fit reach.

Registering the MCP server fit look like this for Codex-style TOML config:

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

The same server go register inside ~/.cursor/mcp.json, ~/.config/goose/config.yaml and the other harness configs automatically during install. If you dey connect several of these for one box, run MCP servers for VPS explain the stdio and process model in more detail.

Point am go self-hosted Ollama endpoint

Because harness dey own model connection, to point Agentlas go local models mean say you go point your harness go Ollama. Ollama add launch subcommand for v0.15 exactly for this work, and e still dey ship for v0.32.9 as of 11 August 2026. E configure existing harness against local models without any environment variable to set:

ollama pull qwen3-coder:30b
ollama launch opencode

Replace opencode with claude, codex or droid, depending on the harness wey you install. Then route request through the local runtime:

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

Successful route go return JSON decision wey name the agent or team wey e select, together with a receipt_id. If e no return anything useful, the usual cause na context length. Agentlas documentation ask for model wey get at least 64k context for sessions wey routing heavy, and e name qwen3-coder, gemma3 and deepseek-r1 as examples. Ollama own guidance for coding tools na the same 64k minimum. Routing decisions carry agent inventory inside the prompt, so model wey get 8k or 32k context go truncate the inventory and make poor selections.

One limitation wey the tagline no go tell you. Ollama, Gemma and DeepSeek no get plugin or command system of their own, so /agentlas slash commands no dey available there. For local-model setup, you control the system through the MCP server and hephaestus route command instead. This na real reduction in available features, and na the honest trade-off for keeping the weights for your own box.

How much RAM one hub of idle specialists dey cost

Nothing. Na the whole answer, and you fit prove am instead of just trust am.

Borrowed hub specialists dey arrive as package artifacts, not processes. Specialist na an agent.md plus one .agentlas/ directory wey get JSON: routing-card.json for triggers and capabilities, memory-map.json for write boundaries, mode-map.json for whether e dey run alone or as team. Dem describe Hephaestus Network as an in-process scheduler wey no get background service. Between tasks, check am yourself:

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

The first two commands no print anything for idle box, because nothing dey resident. The third one print the only cost wey parked hub impose on you, and na disk be that. The disk cost dey grow based on how many specialists you keep plus the bundled embedding model wey the runtime ship with.

So, the memory question na completely about the burst, and the burst na your harness plus your model backend. If harness dey talk to hosted API, resident cost na one process wey use a few hundred megabytes. If you self-host the weights, na the weights be the main 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 na the published download sizes from Ollama model library, not measurements from benchmark run. The KV cache for 64k context dey add on top of every figure above zero. The model wey Agentlas docs mention first, qwen3-coder:30b, need 19 GB of weights before context, and even the 27B Gemma variant need 17 GB. Compared with those numbers, Agentlas layer itself no show for the budget.

How e compare to running one harness

Run one harness against hosted API, and your VPS go carry one process. Add Agentlas, and e go carry that same one process, plus files. The orchestrator no be another long-lived program. Na bigger prompt wey e assemble from packages for disk, then e discard am.

The cost wey change na context, no be memory. Orchestrator wey bring in several specialist cards and their routing metadata go use more tokens per task pass bare harness. For hosted API, na money this one dey cost, no be RAM. For local weights, na time, because longer prompt mean longer prefill for CPU or more work for GPU.

Na why sizing advice for box like this follow model decision, no be agent framework. How to size RAM and CPU for coding agent VPS explain am well, and conclusion still hold here: choose plan based on backend wey you plan run, then add a couple of gigabytes headroom for harness. If you prefer always-on supervisor design for comparison, Omnigent multi-agent harness keep its coordinator resident. Na the opposite trade-off, and e go show directly for idle memory.

Failure modes and the strings wey you go see

hep-build: command not found immediately after clean install. The installer write go ~/.local/bin, but PATH no include am for default Ubuntu image. E mention am for the final line, but the line don scroll pass. Add the export wey show above.

Behaviour change after you rebuild the box. You no set HEPHAESTUS_REF, so the installer use any tag wey current that day by default. Pin am, then record the pin beside your other version numbers.

Routing choose the wrong specialist for local model. The model context window too small for the agent inventory. Move go model wey get 64k or more, then set Ollama context length to match, because the default value lower than wetin the coding tools need.

ollama launch no dey recognised. The subcommand enter Ollama v0.15. Older packages from distribution repository older pass this feature, so install current Ollama.

The install write inside harnesses wey you no expect. The script detect and configure every harness wey e find. E write go ~/.claude/, ~/.codex/, ~/.gemini/, ~/.cursor/ and more. For shared build box, read the script before you run am, and know which of those directories concern you.

Make you run this one now?

Project wey don only ten weeks old and dey get automated releases several times every day no be something wey you suppose put for production workload. The architecture really dey interesting, the license na Apache-2.0, and because the design dey use files, to uninstall am na to delete two directories. These facts make am cheap to test, but expensive to depend on.

For now, better approach na: pin v1.2.0, run am for box wey you fit rebuild, keep ~/.agentlas inside your backups, and read the changelog again before you move the pin. If you want broader survey of other things for this space and how mature each option be, the roundup of self-hosted AI agents na better place to start. self-hosting a Hermes agent on a VPS explain one of the harnesses wey Agentlas dey adapt to.

FAQ

Agentlas OS dey run as server for my VPS?

No. No daemon dey, no listening port dey, and no container image dey inside the repository. Installer dey write runtime inside ~/.agentlas/runtime/ and command wrappers inside ~/.local/bin. Hephaestus Network na in-process scheduler, no be background service. You fit confirm am for idle box: pgrep -af hephaestus no go print anything, and no systemd unit dey to enable. Self-hosting here mean say the code and state dey for your machine. E no mean say service dey listen.

How much RAM idle specialists hub dey use?

None, because idle specialists no be processes. Specialist na agent.md file plus .agentlas/ directory wey dey hold routing-card.json, memory-map.json and similar metadata. So parked hub na disk e dey cost. Use du -sh ~/.agentlas measure am. Memory dey consumed only when task dey run. Na your harness process and model backend dey use the memory, no be Agentlas layer.

Which models I fit use, and I fit point am to my own Ollama?

Agentlas no dey call model APIs by itself. Host harness dey manage credentials and connection, so supported models na any model wey your harness support. For local weights, run ollama launch opencode, and substitute claude, codex or droid. This one configure harness against your Ollama server without environment variables. Use model wey get at least 64k context, like qwen3-coder or gemma3, because routing prompts carry agent inventory and smaller windows dey truncate dem badly.

Which version I suppose install, and why pinning matter here?

Install v1.2.0, the tagged release wey current on 12 August 2026, by setting HEPHAESTUS_REF=v1.2.0 before you run installer. The script own default na version="${HEPHAESTUS_REF:-v1.2.0}". E dey follow whichever version maintainers tag next. Pinning matter pass normal because project publish more than hundred releases for 1.1 series, with several releases on some days. So if you rebuild weeks later without pinning, you no go get the system wey you test.