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
FlagDescription
-r, --repoGitHub repo to build (Dockerfile at the root). Combine with -b, --branch
--publicServe a public, no-login web URL for this agent
--portPort 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 its url. 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 --public at create, press Public on the Overview, or run runberth 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.
  1. Open Settings → Domains and add the hostname, or run runberth domains add <hostname>. For an exact name, also pass --agent-id <agent-id>.
  2. 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-challenge for the certificate.
  3. 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 sets PORT and forwards public traffic on port 8080 to it. Don't hardcode a port, and don't bind 8080 yourself.
  • Persist to /data only. 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 attempt

Env vars, secrets, and sizing are covered in Env vars & sizing; the full flag set for create and deploy is in the CLI reference.