How to Set Up Omnara Self Hosted From the Current Docs
Oct 25, 202614 min read
If you self-host Omnara, you run its open-source server and dashboard on a machine you control instead of using the hosted service, so your agent session data lives on your infrastructure.
Omnara self-hosting is the practice of deploying Omnara's open-source server and dashboard on infrastructure you control, so that the sessions your AI coding agents produce are stored and served from your own machine rather than the hosted service.
You already run a coding agent, and Omnara sits between you and it, so you can follow a session, read what the agent is asking and answer from a browser or phone. That makes its dashboard a list of sessions, not of agents you build.
Omnara self hosted means running the stack yourself
What Omnara is not
Activepieces is where you build agents and automations, with 744 integrations in its MIT-licensed core; it shows what Omnara isn't, a builder of agents.
Launch an agent yourself and its work in progress appears in Omnara's dashboard instead, so the thing you're hosting is a record of those sessions.
What data moves to your server with Omnara
Only one thing moves: the session record. Prompts, agent replies and any code or file contents the agent quoted are stored by your own server and database, not the vendor's.
In exchange, you own uptime, upgrades, backups and access control, and a stale checkout or a skipped setup step becomes your outage.
Who needs it
You need it if a security policy, contract or data-residency rule says session transcripts can't sit on a third party's servers.
If you only want to approve an agent's prompts from your phone, hosted is the shorter path, and self-hosting adds maintenance without adding anything you use.
This takes minutes, not a project: automate it in Activepieces free.
How self-hosted Omnara fits together
Picture one server with a database behind it, a dashboard that reads from it, and a client wrapped around your coding agent. If you want the data on your own machines, a single server URL joins all of it.
I haven't confirmed exact component names against the current README or changelog, so check those before you copy any command.
Server and database
When the client or the dashboard calls the API, the server is what answers, and the database is where session history and messages are stored.
It's also the part you maintain, including backups, upgrades and uptime.
Omnara dashboard access from phone and browser
You read sessions and answer an agent's prompts through the dashboard. It has to reach your server from wherever you're standing, so a server reachable only from your home network will work at your desk and fail on the train.
Test it from a phone on mobile data, not from the same Wi-Fi as the server, before you trust it.
Wrapped around your coding agent, the client forwards its activity to whatever server URL it's configured with.
Left at its defaults, it may point at the hosted service, so your sessions would go there instead of to your server. After setup, start one session and confirm it appears in your own database, not just on screen.
What it costs to self-host
You pay for a server, upgrades and backups. What that buys is session data you can query in the database you just checked. Hosted Omnara skips that work; the platform itself is free, and you can pay as you go with Omnara credits for models at provider token rates and machines by active time.
Confirm these against the current repo README before you start, since requirements change:
- A machine or server you control that stays online
- A database you can reach and back up yourself
- The runtime and dependency versions the repo currently lists
- Network access from wherever your agent runs to that server
Read the table below for who owns the maintenance work, because that's where the options differ most. It sets the three options side by side on the five things that decided my own run.
| Price | Prerequisites | Upgrades and backups | Data location | Setup effort | |
|---|---|---|---|---|---|
| Hosted Omnara | Platform free; pay-as-you-go credits for models and machines | An account | Omnara | Omnara's infrastructure | Lowest |
| Self-hosted Omnara | Free for the software; infrastructure from your provider | The checklist above | You | Your own database | Highest |
| No monitoring layer | None | None | Not applicable | Only on the machine running the agent | None |
Hosting costs beyond self-hosted Omnara software
Once you pick self-hosting, the bill comes from your provider, not from Omnara. Expect separate lines for the server, the database, storage for backups, and outbound traffic.
If none of those lines is worth paying for data location, the hosted row or the no-monitoring row is the honest answer.
Set up self-hosted Omnara
If one of those lines justifies owning the data, setup is six steps. Each has a check that must pass before you continue; a step that merely ran without error hasn't passed.
Take every command from the repository's current README, not from a blog post or an older copy of the docs, including this one.
Clone and configure the Omnara repository
Step 1 is to clone the repository. Check: the checkout contains the README you're about to follow, and its instructions match what is on disk. If they name a file that's missing, you're on the wrong branch or an outdated fork.
Before starting anything, set the environment variables and the database URL the README lists (step 2). Check: connect to that database with a plain client, outside Omnara, and see it answer.
Step 3 is to start the services the way the README says. Check: every process stays up after the first minute, and the server's log shows no database connection errors. A service that starts and then exits hasn't started.
Connect a client and run a first session
To send traffic to your own server, step 4 is to point the client at your server's URL instead of the hosted one. Check: the client reaches your server, and the hosted service sees no traffic from it.
Step 5 is to run one short session. Check: it appears in your own dashboard, and the row is in your own database. If it shows up only in the hosted dashboard, the client is still pointed at the wrong server.
Put self-hosted Omnara behind HTTPS for phone use
Step 6 is to expose the server over HTTPS with a certificate your phone trusts.
Check: open the dashboard from the phone on mobile data, not your home Wi-Fi, and repeat step 5 from there. Anything that works only on your local network isn't yet reachable from outside it.
You can follow the rest of this with the builder open. Start free, no card.
Avoid mistakes that break setups
Every failure below traces back to trusting something older than the current README, issue tracker, or changelog, so check those first and treat everything else as a lead.
When a tutorial names a command, environment variable, or compose file the repo has since renamed, it fails at the first step, or worse, half-works.
Fix: copy nothing from a blog post until you've diffed it against the repo's current setup instructions and recent changelog entries. Check open issues for your exact error before debugging it yourself.
Exposing the server without protection
Leave the database port published and it'll be found. ZoomEye data summarized on DEV Community counts 501,664 exposed Redis services on port 6379, so scanners aren't hunting for you specifically, they're sweeping everything.
Behind that, 27,971 MySQL services are exposed on 3306, and 26,089 PostgreSQL services on 5432.
If your session data lives in a database on one of those ports, an open port means anyone can attempt a login. A sample or default password makes that attempt succeed. Fixes:
- Bind the database to the internal network only.
- Replace every default secret before first start.
- Put the web service behind HTTPS with a certificate you have a renewal plan for.
Skipping Omnara backups and upgrade planning
Lose the disk with no backup and the whole exercise is defeated, because your session history is the reason you self-host. Schedule a database dump, then restore it into a scratch instance once. A backup you've never restored is unverified.
Before upgrading, read the changelog, and update the server and the client together. A mismatched pair can fail in ways that look like network problems.
Don't assume a feature you saw on the hosted product ships in the self-hosted repo. Search the repo for it before you promise it to your team. If you can't find it there, plan without it.
Activepieces for routing self-hosted agent alerts
The relay role
As a relay, and only as a relay, Activepieces is useful here.
It can take an "agent finished" or "needs input" signal and fan it out to Slack, email or a ticket through any of its 744 integrations, but it plays no part in installing or running Omnara.
If you plan without a documented hook on the Omnara side, there's nothing for it to receive.
You watch and answer a coding agent's session in Omnara. Activepieces does none of that.
It never sees the session itself, only whatever notification you choose to send it, so treat it as a downstream consumer of events; with unlimited flows on every plan, including free, one relay per project costs nothing extra.
Keeping Omnara agent alerts on your infrastructure
Once you self-host Omnara, your session data sits on your infrastructure. Activepieces is open source and self-hostable too, so the relay can sit on the same side of that line. Its core is MIT-licensed and runs on your own servers or fully air-gapped.
The enterprise list in the air-gapped docs (SSO, SCIM, custom RBAC, audit logs, release management and secret managers) is the same list the managed cloud carries, including its Frankfurt EU region, so keeping the relay inside your boundary costs you none of those features.
If you route alerts through a hosted automation service, the message content leaves the boundary you just built. Verify what the current Omnara docs say about outbound hooks before you assume one exists.
A minimal workflow to test
In the smallest version I'd test, the workflow below starts with a Catch Webhook trigger, reads a stored connection in step 2, and ends with a Slack "Send Message To A User" action, which is the step selected in the screenshot.
On the right panel you get that step's fields: Connection pointing at "2. Read Connection", plus User, Message and Username. Below them, Generate Sample Data and Test Step let you fire a fake payload at it before anything real depends on it.
Run that test first. A step that passes with sample data proves the Slack side works; it proves nothing about whether Omnara will ever call the webhook.
Who needs this pairing
You need this pairing only if your session data must stay on your own infrastructure. Your team also has to want alerts in Slack, email or a ticket queue rather than a dashboard tab.
If you're on hosted Omnara and fine with that, a separate relay adds a system to maintain for no gain.
Deployment and decision checklist
Settle whether you need the relay at all before you touch a server, because the first step below is the only one that can end the project at no cost. The order matters: each step catches a failure the next one would bury.
- Decide if data location justifies self-hosting. Write down the concrete requirement, such as "session transcripts must stay on infrastructure we control." If you can't name one, stay on hosted Omnara and stop here.
- Re-read the docs and the changelog. Check the current setup guide and the repo's recent changes for required versions and environment variables, and for anything the two disagree on. Where they conflict, the repo wins over any article, this one included.
- Provision a test host. Use a machine that holds nothing you care about, so a failed install costs you nothing.
- Run setup on a non-critical project. Start a real agent session and confirm the data lands on your host, not the hosted service. Record every step where your experience differed from the docs. A successful install screen isn't evidence that data is going where you think.
- Add backups and HTTPS. Then restore a backup onto a clean machine. A backup you've never restored is an untested assumption.
- Roll out. Move one project at a time, and keep the hosted setup available until the first project has run cleanly through a normal working cycle.
A successful install screen isn't evidence that data is going where you think.
Frequently asked questions
For each question below, I'll tell you what I can stand behind and where you need to check the current repo yourself. These are the ones the setup steps leave open.
You pay nothing for the software itself, since the server code is open source. You still pay for whatever runs it: the machine and the database, plus your own time maintaining both.
Check the license file in the repo before you deploy, because license terms are what decide commercial use, not a blog post.
Can I self-host Omnara on a small VPS?
Probably, for a single user, but "probably" isn't a test result. Run it with your real workload and watch memory and disk while an agent session is active.
A server that starts cleanly on an idle box has told you nothing about how it behaves under load. The repo's current requirements for the database and runtime set your floor, so read those first and size up from there.
Does self-hosted Omnara work with agents other than Claude Code?
Whether another agent works depends on which integrations the repo ships today, and that list changes. Don't assume a wrapper that works for Claude Code has an equivalent for another agent.
Look at the repo's supported-agents documentation, then start one real session with the agent you care about and confirm it appears on your server. If it doesn't show up, it isn't supported for your purposes.
How do I update a self-hosted Omnara server?
Treat every update as a change that can break something. Read the release notes for migration steps, back up the database first, and pull the new version.
Then rerun a test session end to end, from agent to server to client. If the update fails, the backup's your way back. Pinning a version instead of tracking the main branch keeps surprise changes out of your deployment.
Is my code sent to Omnara's servers when I self-host?
With self-hosting, session data should go to your server, which is the reason to do it. But "should" is a claim to verify, not accept.
Point the client at your own URL, then watch outbound traffic during a session and confirm nothing leaves for a host you didn't configure. Also check whether the agent itself, such as Claude Code, sends data to its own provider. Self-hosting Omnara doesn't change that.
Related reading
References
Build it
Set this up in minutes.
No code required. Connect your accounts, and Activepieces runs it from there.
Start free Talk to sales
