Public web agents
Any repo with a Dockerfile can be served on a public, no-login HTTPS URL. RunBerth builds it, runs it serverlessly, puts it to sleep when idle, and wakes it on the next visit.
Deploy one
runberth create my-app --repo https://github.com/you/app --public| Flag | Description |
|---|---|
| -r, --repo | GitHub repo to build (Dockerfile at the root). Combine with -b, --branch |
| --public | Serve a public, no-login web URL for this agent |
| --port | Port the public URL sends traffic to. Keep the default, 8080: RunBerth forwards it to the PORT your app binds |
The dashboard's New agent flow takes the same sources: a GitHub repo, a Docker image, or a ZIP upload. Repo and ZIP sources build on a dedicated build machine; see How builds work.
Visibility
Every agent that serves a port has its own address, https://<agent-id>.mtm.sh/, shown on its Overview as URL. It is private until you say otherwise.
- Private (the default). A visitor needs a share link. Your backend mints one for a signed-in user with
runberth.agents.shareLinks.create(agentId, { endUserExternalId })and sends them to itsurl. The first visit swaps the secret for a cookie on that hostname, so pages, assets, and WebSockets all work. A link lasts one hour unless you choose up to 30 days, or no expiry. A link bound to an end user dies when you suspend that end user. - Public. Anyone with the URL may open it, and a visit wakes a sleeping agent. Pass
--publicat create, press Public on the Overview, or runrunberth agents url visibility <agent-id> public. Needs a verified email.
The app sees its own Host and its own cookies. Agent URLs tell search engines not to index them. The older https://api.runberth.com/a/<agent-id> path keeps working for public agents.
Serve it on your own domain
An agent can also answer on a hostname you own. Add one of two kinds of domain:
- Exact, such as
app.yourco.com. It serves one agent at its root. - Wildcard, such as
*.agents.yourco.com. It serves every agent of your account at<agent-id>.agents.yourco.com, including agents you create later. How you deploy does not change.
- Open Settings → Domains and add the hostname, or run
runberth domains add <hostname>. For an exact name, also pass--agent-id <agent-id>. - Create the DNS records the domain lists at your DNS provider: a CNAME that routes the name, a TXT that proves you own it, and for a wildcard a CNAME on
_acme-challengefor the certificate. - Wait for the domain to show live. RunBerth checks every minute and issues the certificate itself. To check now, run
runberth domains check <domain-id>.
To give an agent a readable name under a wildcard, set a label: runberth domains labels set <domain-id> <label> <agent-id> serves the agent at <label>.agents.yourco.com. An agent has one label per domain, and its id keeps working too.
Visibility applies on your domain as well, so a private agent still needs a share link. An account can have three domains. Adding one needs a verified email. Names under runberth.com and mtm.sh are refused. Removing a domain stops serving it at once. For the API, see Custom domains in the REST API reference.
What your app must do
- Ship a Dockerfile at the repo root. Whatever it builds is what runs.
- Listen on
0.0.0.0:$PORT. RunBerth setsPORTand forwards public traffic on port 8080 to it. Don't hardcode a port, and don't bind 8080 yourself. - Persist to
/dataonly. It survives restarts, redeploys, and sleep/wake; the rest of the filesystem is disposable.
A web app does not need the chat contract; that is only for agents you want to talk to. If you want both (a web UI and a chattable agent), implement the two-endpoint contract from Deploy any container.
Sleep and wake
The app auto-sleeps when idle and any request to its public URL wakes it, in about a second, with state intact. Sleeping is not downtime: visitors just wake it. The first request after a sleep waits for the wake; every request after that is answered by a running machine.
Configure and observe
runberth env set my-app DATABASE_URL=postgres://... --reload # encrypted secrets
runberth logs my-app -f # stream logs
runberth history my-app # every build/deploy attemptEnv vars, secrets, and sizing are covered in Env vars & sizing; the full flag set for create and deploy is in the CLI reference.