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.10No 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 -- --yesMore 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 :3000To 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 level | What the agent can do |
|---|---|
| Read only | See 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. |
| Full | Also 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 /healthzby 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.
| Variable | Value |
|---|---|
PORT | The port to listen on, on 127.0.0.1 |
DATA_DIR | Persistent folder that survives deploys; also the working directory |
DATABASE_PATH | $DATA_DIR/app.db |
SIDEYARD_PROJECT, SIDEYARD_RELEASE | Project name and release number |
SIDEYARD_TOKEN, SIDEYARD_API_URL | Authenticate job calls and the email and sign-in APIs |
AWS_*, S3_BUCKET | Only 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/deploysSideyard 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, andRequestChecksumCalculationandResponseChecksumValidationtoWhenRequired. - 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.
- Handle
POST /_jobs/<name>in the app, and checkAuthorization: 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 thejobsmap injobs.go. - Deploy, then create the job in the Jobs tab with a cron schedule: five fields, in UTC unless prefixed with
CRON_TZ=Area/City.@dailyand@every 15mwork 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.
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:
- The app asks Sideyard to start a sign-in, keeps the returned
statein a cookie and sends the browser to the returnedurl. - After the provider, Sideyard sends the browser back to the app with a one-time
codeand thestate. - 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| Path | Contents |
|---|---|
/opt/sideyard/bin/sideyard | The binary |
/etc/sideyard/sideyard.env | Settings; restart Sideyard after changing them |
/var/lib/sideyard/sideyard.db | Projects, domains, releases and encrypted variables |
/var/lib/sideyard/master.key | Decrypts variables. Without it, they're lost. |
/var/lib/sideyard/projects/<name>/ | data/ (the app's $DATA_DIR) and releases/ (the last five binaries) |
| Setting | Meaning |
|---|---|
SIDEYARD_DOMAIN | Base domain; projects get <name>.<domain> |
SIDEYARD_PUBLIC_IP | The server's public IPv4, for checking where domains point when the VM is behind NAT |
SIDEYARD_DASHBOARD_HOST | Serve the dashboard somewhere other than sideyard.<domain> |
SIDEYARD_UPDATE_SOURCE | Where 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 -- --uninstallLimits
- 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.