Docs

Everything you need to run apps on Sideyard, kept short. Your coding agent reads the details from the app's AGENTS.md; this page is for you.

Introduction

Sideyard runs many small web apps on one server you own. It's a single Go binary with Caddy built in: it serves every app over HTTPS, deploys them without downtime, and gives each one a database editor, backups, scheduled jobs, email, file storage and logs.

Every app has the same shape: a Go backend with its React frontend embedded, and SQLite for data, compiled into one Linux binary. The fixed stack is the point. One small server holds many apps, the dashboard understands each app's database and jobs, and your agent has one well-defined target to build for.

  • You or your agent build the binary on a laptop or in CI. Node and Go never touch the server.
  • Sideyard starts the new release next to the running one, waits for its health check, then switches traffic. A release that fails never takes traffic.
  • Each app runs as its own Linux user in its own systemd unit, with a memory limit and write access only to its data folder.

Install

You need a fresh Ubuntu or Debian server (amd64 or arm64) with ports 80 and 443 reachable. A 4 GB, 1 vCPU VM is plenty for a handful of small apps.

1. Point a domain at it

Add a wildcard A record (and AAAA if the server has IPv6). On Cloudflare, set it to DNS only: Sideyard gets its own certificates.

*.example.com   A   203.0.113.10

No domain yet? Skip this. The installer offers a free 203-0-113-10.sslip.io name for trying it out.

2. Run the installer

curl -fsSL https://github.com/rabeeh-ta/sideyard/releases/latest/download/install.sh \
  | sudo bash

It asks for the domain and an admin password, starts Sideyard as a systemd service and prints the dashboard's address, https://sideyard.example.com. Apps get <name>.example.com.

Without questions, for scripts and cloud-init:

curl -fsSL https://github.com/rabeeh-ta/sideyard/releases/latest/download/install.sh \
  | sudo SIDEYARD_DOMAIN=example.com bash -s -- --yes

More in the install guide.

Your first app

The quickest start is the New app prompt: paste it into your coding agent with a description of what you want. The agent creates the starter (Go server, migrations, jobs, email, React frontend and deploy workflow), saves the contract as AGENTS.md and builds your app inside it. Moving an app you already have? Use the Existing app prompt next to it.

Without an agent, copy the starter yourself:

git clone https://github.com/rabeeh-ta/sideyard
cp -r sideyard/templates/starter my-app && cd my-app
cd web && npm install && cd ..
make api       # Go server on :3000, data in ./data
make web-dev   # Vite on :5173, forwards /api to :3000

To put it online, create a project in the dashboard and follow the Connect deploys steps it shows, or connect your agent and let it deploy.

Connect an agent

Sideyard serves MCP at https://sideyard.example.com/mcp, so an agent can create projects, deploy, read logs and fix what broke without you opening the dashboard. On the dashboard's MCP page, make a token, pick your agent (Claude Code, Codex, Cursor, VS Code, Gemini CLI or another) and copy its setup. For Claude Code it's:

claude mcp add --scope user --transport http sideyard \
  https://sideyard.example.com/mcp \
  --header "Authorization: Bearer sy_mcp_…"

Then ask it to deploy the app to Sideyard. It builds the binary, uploads it with a one-time ticket, and reads the logs if the health check fails.

Token levelWhat the agent can do
Read onlySee projects, status, logs, variable names and jobs; run read-only SQL.
Manage (default)Also create projects, deploy, restart, stop, roll back, and change variables, settings, domains and jobs.
FullAlso delete projects with their data.

No level can read a variable's value, change platform settings or touch the admin password. Every call is logged on the MCP page, and revoking a token stops it at once. Clients that connect only with OAuth, such as claude.ai's connectors, can't connect yet.

The app contract

Any app that keeps to these rules runs on Sideyard. The starter already does, and its AGENTS.md is the full version.

  • Listen on 127.0.0.1:$PORT. Sideyard's proxy owns the domain and HTTPS.
  • Keep persistent files in $DATA_DIR. Everything else is replaced on each deploy, and read-only on the server apart from a private /tmp.
  • Answer the health check (GET /healthz by default) with a 2xx or 3xx once the app can serve.
  • On SIGTERM, finish in-flight requests and exit within 10 seconds.
  • Build with CGO_ENABLED=0 GOOS=linux, so use the pure-Go SQLite driver, modernc.org/sqlite.
VariableValue
PORTThe port to listen on, on 127.0.0.1
DATA_DIRPersistent folder that survives deploys; also the working directory
DATABASE_PATH$DATA_DIR/app.db
SIDEYARD_PROJECT, SIDEYARD_RELEASEProject name and release number
SIDEYARD_TOKEN, SIDEYARD_API_URLAuthenticate job calls and the email and sign-in APIs
AWS_*, S3_BUCKETOnly while a bucket is connected

Memory is capped at 512 MB and CPU is unlimited by default; change both in Settings → Runtime.

Not a Go app? Any Linux binary that keeps to the contract runs. Start arguments in the same place passes flags with $VARS expanded. PocketBase, for example, runs with serve --http=127.0.0.1:$PORT --dir=$DATA_DIR/pb_data and the health check path /api/health.

Deploys

A deploy is one binary upload, authenticated with the project's deploy token:

make build    # builds web/dist, then a Linux binary with it embedded: ./app
              # (make build GOARCH=arm64 for an ARM server)
curl --fail-with-body -H "Authorization: Bearer $SIDEYARD_TOKEN" -F binary=@app \
  https://sideyard.example.com/api/projects/my-app/deploys

Sideyard starts the new release on a free port and waits up to 60 seconds for its health check. If it passes, traffic moves to it and the old process stops. If not, the new one stops, the old one keeps serving, and the upload fails with 422 and the release log.

From GitHub

The starter's .github/workflows/deploy.yml deploys every push to main. Set the secret SIDEYARD_TOKEN and the variables SIDEYARD_URL and SIDEYARD_PROJECT (and SIDEYARD_ARCH=arm64 on an ARM server). From a laptop, put the same values in .env.deploy and run make deploy.

Rollbacks and restarts

The Deployments tab keeps the last five releases, and Roll back starts an older one the same health-checked way. Restarts and variable changes go through that path too, so none of them cause downtime.

Migrations don't roll back. Append new ones and keep each compatible with the previous release's code: add tables and columns now, drop or rename them in a later deploy.

The deploy token is shown once, when the project is created. Settings → Deploy token makes a new one.

Variables

In the Variables tab, paste KEY=value lines as in a .env file. Values are encrypted at rest, and saving restarts the app without downtime. The app gets these plus the ones in the contract, nothing else: Sideyard's own environment is never passed on.

Domains

Every project gets <name>.example.com from the wildcard record. To add your own domain, point an A record (AAAA for IPv6) at the server, or a CNAME at sideyard.example.com for a subdomain, then add it on the project's Domains page. HTTPS is set up automatically. Behind Cloudflare, keep the record DNS only.

The page shows the DNS record each domain needs, whether it points at this server yet, and which certificate Sideyard holds for it.

Database

The app's database is $DATABASE_PATH. The Database tab finds every SQLite file in $DATA_DIR.

  • Table Editor: browse, filter and edit rows; create, rename and drop tables and columns.
  • SQL Editor: runs read-only until you confirm a write. Saved queries are shared between browsers.
  • Download: a consistent snapshot, even while the app is writing.
  • Import: checks the file, swaps it in and restarts the app. If the app then fails its health check, the old file goes back. Replaced files stay in $DATA_DIR/.sideyard/backups (the last 10).

To bring data from an existing app, create the project, upload its file with Database → Add a database at the path the app expects, then deploy. Copy it with sqlite3 app.db ".backup copy.db" so the copy is consistent while the old app runs.

Files and storage

Keep uploads and large files in an S3 bucket, with their metadata in SQLite. In the Storage tab, connect a bucket on AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces or any S3-compatible service. Sideyard checks the key, sets AWS_ENDPOINT_URL_S3, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and S3_BUCKET, and restarts the app. The tab also lets you browse the bucket's files.

  • The AWS SDK for Go v2 reads the AWS_ variables by itself.
  • Off AWS, set UsePathStyle, and RequestChecksumCalculation and ResponseChecksumValidation to WhenRequired.
  • Keep the bucket private and serve files through the app or with presigned URLs. Give each project a key scoped to its own bucket.

Jobs

A scheduled job is an HTTP call from Sideyard into the app, so the app needs no timers and never runs a job twice at once.

  1. Handle POST /_jobs/<name> in the app, and check Authorization: Bearer $SIDEYARD_TOKEN. Answer 2xx with text for the run's output, or an error status to fail it. In the starter, add a function to the jobs map in jobs.go.
  2. Deploy, then create the job in the Jobs tab with a cron schedule: five fields, in UTC unless prefixed with CRON_TZ=Area/City. @daily and @every 15m work too.

Runs missed while the app was down collapse into one catch-up run, and a run is skipped while the previous one is still going. Each job has a timeout and optional retries, and the last 100 runs are kept with their output. /_jobs/* answers 404 on every public domain, so only Sideyard can trigger it. Keep jobs idempotent.

Email

On the dashboard's Email page, set one SMTP server (any provider), a default sender and the sender domains you've verified with the provider. Each project picks its sender in its Email tab, and the app sends with its own token:

curl -X POST "$SIDEYARD_API_URL/api/projects/$SIDEYARD_PROJECT/email/send" \
  -H "Authorization: Bearer $SIDEYARD_TOKEN" -H "Content-Type: application/json" \
  -d '{"to": ["ada@example.com"], "subject": "Hello", "text": "Plain text", "html": "<p>Optional</p>"}'

Up to 50 recipients per email and 60 emails a minute per project. The Email tab logs the last 500. The starter's sendEmail in email.go does this for you.

Sign-in with Google and GitHub

On the dashboard's OAuth page, set up Google or GitHub once: create an OAuth client with the provider, register the callback URL the page shows (https://<dashboard>/api/oauth/google/callback, the only one you need however many apps use it) and paste in the client ID and secret. Test sign-in checks it end to end. Every app on the server can then sign people in, and never sees the client secret:

  1. The app asks Sideyard to start a sign-in, keeps the returned state in a cookie and sends the browser to the returned url.
  2. After the provider, Sideyard sends the browser back to the app with a one-time code and the state.
  3. The app checks the state against its cookie and trades the code for who signed in.
curl -X POST "$SIDEYARD_API_URL/api/projects/$SIDEYARD_PROJECT/oauth/start" \
  -H "Authorization: Bearer $SIDEYARD_TOKEN" -H "Content-Type: application/json" \
  -d '{"provider": "google", "redirect": "https://notes.example.com/auth/callback"}'
# → {"url": "https://accounts.google.com/…", "state": "…"}

curl -X POST "$SIDEYARD_API_URL/api/projects/$SIDEYARD_PROJECT/oauth/exchange" \
  -H "Authorization: Bearer $SIDEYARD_TOKEN" -H "Content-Type: application/json" \
  -d '{"code": "…", "state": "…"}'
# → {"provider": "google", "id": "…", "email": "ada@example.com", "emailVerified": true, "name": "Ada", "avatarUrl": "…"}

The redirect must be on one of the project's domains, and a code works once, for that project and state, within two minutes. The app keeps its own users and sessions; the project's Sign-in tab lists who has signed in. The starter's startSignIn and finishSignIn in auth.go do all of this.

Logs and metrics

  • Logs tab: the app's output and Sideyard's events (deploys, restarts, health changes). Search covers the whole log, not just what's on screen.
  • Project page: memory, CPU and health.
  • System page: the server's CPU, memory, disk and network over the last day, with each app's share.

Sideyard checks every app's health every 30 seconds and logs when one turns unhealthy or recovers.

Backups

On the dashboard's Backups page, connect a bucket used only for backups. Every 6 hours by default, Sideyard snapshots its own database and every app's SQLite files and uploads them gzipped. Copies older than 14 days are deleted, except the newest three of each. Restore one from Database → Backups in S3.

  • The master key, which decrypts variables, isn't uploaded. Download it from Platform settings → Security and keep it off the server.
  • Only SQLite files are backed up. Keep other files in a bucket.
  • If the server dies, you lose up to one interval of writes.

To rebuild a dead server, see what to back up.

Updates

Sideyard checks for a new release every 6 hours. Platform settings → Updates installs it with one click, or automatically. Apps keep serving throughout; the dashboard pauses for a second or two. If a new version fails to start three times in a row, Sideyard puts the previous one back by itself.

On the server

sudo sideyard status            # what's running, and where its files are
sideyard help                   # the other commands
sudo sideyard reset-password    # new admin password, signs out every browser
journalctl -u sideyard -f       # Sideyard's own log
systemctl list-units 'sy-*'     # one unit per running release
PathContents
/opt/sideyard/bin/sideyardThe binary
/etc/sideyard/sideyard.envSettings; restart Sideyard after changing them
/var/lib/sideyard/sideyard.dbProjects, domains, releases and encrypted variables
/var/lib/sideyard/master.keyDecrypts variables. Without it, they're lost.
/var/lib/sideyard/projects/<name>/data/ (the app's $DATA_DIR) and releases/ (the last five binaries)
SettingMeaning
SIDEYARD_DOMAINBase domain; projects get <name>.<domain>
SIDEYARD_PUBLIC_IPThe server's public IPv4, for checking where domains point when the VM is behind NAT
SIDEYARD_DASHBOARD_HOSTServe the dashboard somewhere other than sideyard.<domain>
SIDEYARD_UPDATE_SOURCEWhere to look for releases (a fork's repository), or off

To uninstall, which lists everything it removes and asks before doing it:

curl -fsSL https://github.com/rabeeh-ta/sideyard/releases/latest/download/install.sh \
  | sudo bash -s -- --uninstall

Limits

  • No Postgres, Redis, Docker, queues or other runtimes, by design. Build it with SQLite, goroutines and jobs.
  • One server: no replicas or autoscaling. Backups protect your data, not your uptime.
  • Sideyard doesn't sign in your app's users; the app handles its own accounts.
  • One admin user, signing in with a password.
  • No alerts yet. Health and backup failures show in the dashboard and logs.
  • Rolling back a release doesn't roll back its migrations.

How it works inside: architecture and MCP.