Seamside Handbook - hn Reader

Getting started

Welcome to Seamside

Seamside is a local-first creative workspace for making things together. Everything you create lives on your device first, then syncs directly with the people you invite. There is no central server, no cloud account, no signup form — pick a name, and you're ready to build.

Your first space

A space is a shared canvas where you and your collaborators gather. Think of it like a room: you open it, you fill it with things you care about, and anyone you invite walks into the same room in real time.

If you've just finished setup, your first space is already waiting for you — with a document and a whiteboard placed inside so there's something to touch right away. To make another:

From the home view, click new space.
Give it a title — something like "Sketches" or "Weekly planning" works well.
Pick an accent color from the swatches, or sample your own from the color picker below them.
Confirm and the space opens — you are inside it.

Drop in your first frame

A frame is a little app that lives inside a space. Notes, a whiteboard, a chat box, a game, a sketchpad — frames are how you actually get things done in Seamside.

Press Cmd+K (or Ctrl+K) to summon Conjure Studio — Seamside's frame picker.
You can also drag a rectangle anywhere on the space's canvas to mark where the frame should go, and Conjure will pop open right there.
Browse the bundled frames, pick one that looks useful, and it drops into your space. Click it and start playing.

That's it for the basics

You now have a space with a frame in it. Everything else in this manual builds on those two ideas: spaces hold your work, and frames are what you work with. From here, you can invite friends, link your other devices, share data between frames, and even build new frames of your own. Welcome aboard — let's keep going.

People: add, chat, collaborate

Add someone to your people

In Seamside, the people you connect with show up under People. Adding someone is a two-step handshake — both sides have to accept, so nobody ends up in your list without agreeing to it.

Open the People tab in the nav at the bottom of the screen.
Click the + in the column header to start an invite. Seamside gives you a link.
Send that link however suits you — chat, email, a paper note in a shared book.
When they open the link, they're asked if they want to connect. Once they accept, they appear in your people list and you appear in theirs.

If the other person is on the same local network, they may even show up under nearby automatically — both of you can tap each other's row to connect, no link needed.

Chat one-on-one

Click any person in your people list to open their detail and chat. Messages sync when both of you are online. If someone is offline, your message waits patiently and delivers the next time you are both connected.

Start a voice or video call

From a person's detail view, hit the call action. If they're online they'll see an incoming call and can pick up. Calls run directly between your devices — no third party is routing your audio or video.

Invite someone into a space

Once you're connected, you can pull them into a space:

Open the space you want to share and head into its settings.
Invite a person from your people list.
Pick their role — viewer, collaborator, or admin.
They get an invitation under their Spaces tab. Once they accept, the space lights up for both of you and you can work in it together.

Good to know

Presence dots tell you who's currently online — filled means active, hollow means offline. No guesswork, no fading dots.
You can give a contact a petname — a private nickname only you see — without changing the name they picked for themselves.
Removing a contact only affects your side. They still have their copy of any shared spaces unless you remove them from those spaces too.

Working in spaces

Spaces are shared rooms

A space is the main place where work happens in Seamside. When you're inside a space, everyone else who's also there sees the same contents, and any changes flow live between you. Each space is its own canvas — drop in as many or as few frames as you like, arrange them how you want, and let the space grow with the project.

Moving around

You can pan the canvas by scrolling, zoom with Cmd/Ctrl+= and Cmd/Ctrl+- (or pinch), and zoom out to hyperspace view with Shift+Escape to see everything at once. Your viewport is yours — sliding around on your screen doesn't yank anyone else's view — but adding, removing, or repositioning a frame is shared with everyone in the space. The full list of moves lives in the keyboard shortcuts chapter.

The lock

Each space has a lock in its header. Locked keeps every frame pinned exactly where it is — nothing gets nudged by a stray drag. Unlocked lets you move and resize freely. Editors start unlocked; viewers are always locked. When a space is locked and you just need to scoot one thing, hold Cmd/Ctrl+E — frames unlock while you hold it and snap back to locked when you let go.

Roles inside a space

Owner — the person who made the space. Full control, including handing over ownership.
Admin — can change membership and most settings.
Collaborator — can use frames and edit content.
Viewer — can use the frames in the space, but can't add, remove, resize, or otherwise alter them.

Archiving, ignoring, and leaving

You can archive a space to tuck it out of your main list without deleting it — unarchive any time. If someone invites you to a space and it's not for you, hit ignore and it slides into a quiet "ignored" section you can reverse later. And if you're done with a shared space, you can leave — the space keeps running for everyone else who stays.

Frames: using and making

What a frame is

A frame is a small, self-contained app that runs inside a space. Seamside ships with a bundled catalog of frames — notes, sketchboards, timers, chat widgets, mini games, and more — and you can install additional ones from remote catalogs or build your own from scratch.

Adding a frame to a space

Open Conjure Studio with Cmd+K (or Ctrl+K) to browse frames you can drop into the current space. You can also drag a rectangle on the canvas to place a frame exactly where you want it. The same frame can be placed more than once — each placement is independent and keeps its own state, so two copies of the sketchboard happily co-exist.

Frame types

Tandem — runs in Seamside's shared, sandboxed runtime. Fast, safe, and the default for most frames.
Solo — runs in its own dedicated sandboxed process, for frames that want more room to themselves.
Hosted — runs its own server process that Seamside manages — for frames built on things like Node, Python, or Docker.
Proxy — points at any URL, no special runtime required. That can be an internal address (a sandboxed server you're running locally, like a Docker app) or an external one (a specific site you want to embed).

Making your own frame

Seamside includes a Frame Workshop — a built-in editor where you can design and build a new frame, with optional AI help if you've set up an AI capability. Pop open a frame's details and choose edit in workshop, or start fresh with a brand-new frame. You don't need to be a professional developer; start tiny, iterate, and have fun. Some of the most delightful frames in Seamside started as a five-minute "what if?".

Frames can travel

Move it to another of your devices. A frame runs on one of your devices, but it doesn't have to stay there. Move a running frame — data and all — to a sibling device, and every placement and share link keeps working without missing a beat.
Copy someone else's frame. When a frame in a shared space is marked as freely reusable by its maker, you'll see the option to copy it to your own device — edit it, remix it, make it yours.

Keeping frames fresh

Frames installed from a catalog show an update beacon when a newer version is available — on the frame itself and in the nav. Update one from its details, or take care of everything at once with update all. Your customizations and any data the frame stores stay intact. One honest trade: once you edit a catalog frame yourself, it becomes fully yours — and steps out of catalog updates so your changes are never overwritten.

Syncing data with tables

What tables are for

A table is a structured, shared dataset — rows and columns, like a spreadsheet, but synced in real time with anyone you invite. Tables are deliberately separate from spaces so the same dataset can power many frames across many spaces. Build a "tasks" table once and let a list frame, a kanban frame, and a calendar frame all share it.

Create a table

Open the Tables tab in the nav.
Click the + in the column header to start a new table.
Give it a title and a short description.
Add columns — pick a type for each one: Text, Integer, Real (decimal numbers), or Blob (raw binary data).

Adding and editing rows

Rows can be added by hand from the table's detail view, or by a frame that's bound to the table as a data source. When anyone adds or edits a row, the change rolls out to everyone else with access — even if some of you are offline at the time. Sync catches up cleanly when you're back online.

Frames and tables together

Frames can declare the tables they need ("I'd like a table called tasks with these columns…") and the space owner picks which table to bind it to — either an existing one that fits, or a new one created on the spot. The frame talks to its local copy of the table; Seamside handles the sync underneath. You don't have to think about it — it just works.

Sharing tables

Like spaces, tables have per-person roles: viewer, collaborator, admin, or owner. Invite anyone from your people list and they'll see the table appear under their Tables tab as a pending invitation.

Deleting rows

Deleted rows are marked as removed but their history sticks around just long enough for offline peers to catch up cleanly when they reconnect. Delete confidently — Seamside won't surprise someone with a phantom row that should've been gone.

Capabilities: connecting to the outside world

What a capability is

A capability is a service that frames can ask for: "call an AI model", "talk to a local tool", "fetch a weather API". Seamside keeps capabilities separate from frames so a frame has to explicitly request access — and you stay in control of what's allowed.

Kinds of capabilities

Device — things that run on your computer (local tools, files, OS integrations).
API — external services like AI providers. Plug in an API key once and any frame you allow can use it.
Remote — a capability hosted by another peer in your network.

Setting one up

Open the Capabilities tab in the nav.
Capabilities that still need configuration sit under needs setup with a setup badge — click one to drill in.
Enter whatever it asks for (an API key, a path, a URL) and save. The capability moves to active and frames can start using it.

Once a capability is active, Seamside tracks whether it's reachable. If something goes offline (server down, network blip), the capability slides into the offline section so you know what's going on at a glance.

Installing more capabilities

Like frames, capabilities can come from catalogs. Anything listed under available to install can be pulled in with one click. You can also add remote catalog URLs from Settings → Catalogs to share a curated set across a team or community.

Setting your default AI

Once you have at least one AI capability set up, head to Settings and choose your default AI provider. That's the one Conjure Studio and the Frame Workshop will reach for when they need a hand from an AI. Each AI capability also lets you pick which model handles quick touch-ups, standard builds, and deep work — with sensible fallbacks so things keep working even if you leave a slot blank.

Keeping control

You can turn off, reconfigure, or remove a capability at any time. Frames that relied on it just stop having access — they don't get to bypass your decision. You're the gatekeeper, always.

Using Seamside on multiple devices

One person, many devices

Your Seamside identity belongs to you, not to a single computer. A single identity can run Seamside on as many devices as you like — laptop, desktop, phone, even an always-on server (there's a whole chapter on that) — and to everyone else you appear as one person, no matter which device you're on at the moment.

Admin vs standard devices

Each device you link is either admin or standard. Admin devices can pair new devices, revoke old ones, or update your profile. Standard devices have all the day-to-day powers but defer those identity-level changes to an admin device. Your first device is always admin; subsequent ones default to standard for safety, with the option to promote.

Linking a new device

Install Seamside on the new device.
On a device you're already signed into, open the Devices tab and click the + in the column header (Add device).
If both devices are on the same local network, you'll see the new one waiting under nearby. Otherwise, share the pairing link — on a phone, you can simply scan it as a QR code.
Confirm the fingerprint matches on both devices, choose admin or standard, and you're paired.

If no admin is online when a standard device tries to add a sibling, the request waits patiently as a pending approval until you can review it from an admin device. Nothing slips through quietly.

Seeing your devices

The Devices tab shows every device tied to your identity: the one you're currently on (marked this device), and your siblings under my other devices. Online ones light up; offline ones stay calm. Drill into any of them to rename or remove. Every device is in charge of its own name — rename the one you're on and your other devices pick the change up automatically.

What syncs between devices

Your people and invitations.
Your spaces and the frames placed in them.
Your tables and their contents.
Most settings — a few device-specific ones stay on the device where you set them.

Nearby devices

When another Seamside device is broadcasting on your local network — yours or someone else's — it shows up under nearby. You can claim a nearby device of your own to start the linking flow, or connect with a nearby person to add them as a contact. No invite link needed; the network does the introduction.

Seamside on a remote server

A light that stays on

Your laptop sleeps. Your phone runs out of battery. A Seamside server doesn't — it's the same Seamside app, running without a window on a machine that's always on, hosting your frames and keeping your shared spaces reachable around the clock. Nothing about it is a different product: same frames, same spaces, same rules.

The easy way: the installer

On any Linux server you control (a small VPS works great), run the Seamside server installer script as root. The quickest way is a single command:

curl -fsSL https://seamside.com/seamside-manager.sh | sudo sh

New to this? Log in to your server the way your host describes — usually an SSH connection or a web-based console that drops you at a terminal, a plain window where you type commands. Copy the line above, paste it into that terminal (right-click or Ctrl+Shift+V in most terminals), press Enter, and then just follow the prompts. That single command downloads the installer and manager, and from there it walks you through standing up and looking after an always-on Seamside instance — install it, check on it, update it, or remove it — all from the same friendly menu.

Seamside is light on its feet: it runs happily on very modest hardware — even a 512 MB RAM server, often the cheapest option a host offers, is plenty. The main thing that asks for more is serving lots of heavy custom frames; ordinary spaces and frames leave room to spare.

Whichever way you start it, the installer walks you through everything:

Name the instance (you can run more than one on the same machine).
Choose what kind of server it is — one of your devices, or its own account (more below).
Pick where its data lives, and set a protection passphrase — letting the installer generate a strong one is the recommended path. It's stored in a root-only file the service reads at startup.
The installer downloads the latest signed release, sets up a system service, and starts it.

A Seamside server needs no open inbound ports — it makes direct outbound connections just like the desktop app, so it's comfortable behind a strict firewall (the installer can even set one up for you).

Two kinds of server

One of your devices. Paste a pairing link during install and the server joins your identity as a sibling — approve it from your own device and it shows up in your Devices tab like any other. Great for keeping your frames running and your spaces synced while your other devices come and go.
Its own account. Give the server a fresh identity of its own — handy for a group, club, or organization where the server is the host. You name one or more operators at install time: people allowed to manage it remotely. At first startup, the server prints an invite link for each operator to connect with.

Driving it from your chair

To administer a server, open it from your Devices tab (or, for operators, from its entry under People) and choose connect. A separate, clearly marked window opens showing the server's own screen — its spaces, its settings, its frames — and you drive it as if you were sitting at it. One person controls it at a time, and actions that only make sense at the machine itself (opening local folders, launching editors, exporting keys) politely stay off-limits from afar.

Operators can be removed at any moment — revoking one takes effect immediately, closing any session they had open.

It looks after itself

The server checks for signed updates on its own, installs them in place, and restarts into the new version. If a new version fails to start properly, it rolls back to the previous one automatically. No ladder, no server room, no 2am drive.

One thing to keep safe

The passphrase file created at install protects the server's data at rest. Keep a copy of it somewhere safe alongside any backups of the server's data folder — the two belong together.

Prefer to set things up by hand? Every step the installer takes is available as plain command-line options — see the command line chapter.

Backups and your private key

Backups happen by themselves

Seamside quietly snapshots your data once a day — it's on by default, no setup required. Each backup is a single compressed archive of everything on this device: your spaces, your frames and the data inside them, your tables, your settings. Your databases stay encrypted inside the archive, just as they are on disk.

Tuning it

Under Settings → device backups you can see when the last backup ran, change how often backups happen, cap how much disk they use, and set how many to keep (older ones are pruned automatically; the newest is always kept). Hit backup now any time for an immediate snapshot, and use the folder icon to open the backups folder and see the archives themselves.

The one thing a backup can't hold

On a desktop or laptop, your device's private key — the root of your identity and the key to your encrypted data — lives in the operating system's own keychain, not in Seamside's files. That keeps it safe day to day, but it means a data backup alone isn't the complete set. For that, export the key:

Open Devices → this device and choose export private key.
Pick a password (at least 8 characters) and confirm it. Remember it — there is no recovery.
Seamside writes a password-protected key file to your Downloads folder.

Anyone holding both the file and the password can act as this device, so treat the pair with respect: store the file somewhere safe, and keep the password somewhere else safe.

Keep copies off this device

Backups land in a folder on the same machine they protect — which guards against mistakes, but not against a lost or broken computer. Copy the archive and your key file to somewhere that isn't this device: an external drive, another machine, wherever you keep precious things.

Restore: on its way

Restoring from a backup isn't available in the app yet. The pieces are deliberately in place — the daily archives and the password-protected key file are exactly what a restore needs — but the guided experience that takes a fresh device and brings everything back is still being built, and will arrive in a future release. Until then, think of your backups and key file as a safety net you're weaving for that day: make them now, keep them safe, and the restore feature will know just what to do with them.

Activity, presence, and notifications

The Activity tab

The Activity tab in the nav shows what's happening right now — who's online, which frames are running, what just changed. It's the fastest way to catch up when you wake Seamside back up after a break.

Presence dots

Wherever you see a little dot next to a person, space, or table, that dot tells you about live state. Filled means active and online; hollow means offline. Dots don't pulse or fade — their meaning is always definite, so a glance tells you exactly where things stand.

The radio feed

The radio is your live notification stream — chat messages, space invitations, frame events, peer arrivals. Click any item to jump straight to the thing it's about. The radio gently fades older items so the freshest ones stand out.

Calls in the nav

When you're on a voice or video call, a small on-call indicator parks itself in the nav with a hangup button. You can keep moving around Seamside — opening other spaces, editing tables, conjuring frames — while the call quietly stays in the background.

Sounds

Seamside plays a subtle sound when something noteworthy happens, like a new chat message or an incoming call. Mute it from Settings any time if you prefer a silent workspace.

Keyboard shortcuts

How to read this

Shortcuts are written as Cmd/Ctrl — that's Cmd on a Mac and Ctrl on Windows and Linux. A couple of canvas moves use the literal Ctrl key on every platform; those are called out below.

Everywhere

Cmd/Ctrl+K — open or close Conjure Studio.
Cmd/Ctrl+E (hold) — momentarily unlock the frames in the active space; they re-lock when you let go.
Shift+Escape — toggle hyperspace, the zoomed-out map of your spaces, frames, and people.
Escape — step back, one layer at a time: it closes whatever is frontmost (a viewer, fullscreen frame, dialog, the nav, Conjure, a selection) — and when nothing is open, it hops between Home and your last space.

In a space

Scroll or two-finger swipe — pan the canvas.
Ctrl+scroll (or pinch on a trackpad) — zoom toward the cursor.
Cmd/Ctrl+= / Cmd/Ctrl+- — zoom in / out a step.
Cmd/Ctrl+0 — glide back to 100% zoom.
Cmd/Ctrl+9 — fit every frame into view.
Drag on empty canvas (unlocked) — sketch a rectangle and Conjure opens to place a frame right there.
Drag a frame's grab bar, or Ctrl+drag anywhere on its body (literal Ctrl on all platforms) — move the frame. Drag its edges to resize.

On the home grid

Arrow keys — move between cards; Enter opens the focused one.
Just start typing — Conjure opens with your first character already in the box.

In Conjure Studio

Arrow keys — move through results and columns; Enter picks the selected item.
Tab — switch from searching to describing something new to build.
Cmd/Ctrl+Enter — send your description off to be built.
Escape — close Conjure.

Chat

Cmd/Ctrl+1 through 9 — jump straight to a pinned chat.
Cmd/Ctrl+` — jump to unread: opens the first pinned chat with unread messages, and walks the queue on repeated presses.
Cmd/Ctrl+] / Cmd/Ctrl+[ — cycle forward / back through pinned chats.
Enter — send; Shift+Enter — new line; type : for emoji autocomplete.

In the nav

Arrow keys — move along the rail and through columns; Enter opens the focused row.
/ — jump to the column's search box.
Escape — clear the search, then collapse the nav.

Building frames

Cmd/Ctrl+Enter — send your request in the Frame Workshop (plain Enter makes a new line).
Cmd/Ctrl+S — save the active file in the code editor.

One deliberate absence

There's no "reload" shortcut — Cmd/Ctrl+R and F5 do nothing on purpose. Seamside keeps itself current; a browser-style refresh could only interrupt something mid-flight.

Command line options

You may never need this

Launching Seamside normally just opens the app — no flags required, ever. The command line exists for two power moves: running a server, and connecting AI coding tools. Here is the complete user-facing set.

seamside serve — run as a server

Runs Seamside as an always-on, windowless server (see the Seamside on a remote server chapter for the friendly tour — and note the installer script handles all of this for you).

--data-dir <folder> — where the server keeps everything: keys, databases, spaces, frames. Required.
--port <number> — override the local port Seamside uses internally. Optional.
--accept-terms-of-service — acknowledge the Terms of Service at seamside.com/terms. Required to stand up a new server; a harmless no-op afterward, so it's safe to leave in place. (The installer script asks you to accept these for you.)
--new-user "<name>" — first run only: mint a fresh identity with this display name. Ignored once the identity exists, so it's safe to leave in place.
--join-user <pairing-link> — first run only: join your existing account as a sibling device, using a pairing link from your own Seamside. You approve it from your device. Also safe to leave in place. (Use either --new-user or --join-user, not both.)
--control-by-users <id,id,…> — for a server with its own account: name the people (by their Seamside user ID) allowed to manage it remotely. At startup the server prints an invite link for each.

The server passphrase

A server protects its data at rest with a passphrase — and deliberately never accepts it as a command-line flag (flags are visible to other programs on the machine). Provide it one of two ways:

A systemd credential named seamside-key-passphrase — the installer sets this up for you, pointing at a root-only file. Preferred.
The SEAMSIDE_KEY_PASSPHRASE environment variable — for setups without systemd.

seamside mcp — connect AI coding tools

Lets tools like Claude Code, Cursor, VS Code, or Windsurf build frames alongside you, with their own tightly scoped access you can revoke.

mcp install — set up a tool in one step. Add --client to pick which one (claude-code is the default; cursor, vscode, windsurf, or manual), and --name to label the grant.
mcp config — print the configuration instead of installing it, for pasting by hand (--format picks the flavor).
mcp list — show every grant you've issued.
mcp revoke <id> — cut a grant off.

Odds and ends

SEAMSIDE_DISABLE_MDNS=1 — turn off local-network discovery. Servers do this automatically; set it yourself if you'd rather not be seen under "nearby" on a shared network.

A handful of other flags and variables exist purely for Seamside's own test harness — they're intentionally undocumented here.

Privacy, trust, and how your data is stored

Local-first by design

Everything you create lives on your device first. Seamside doesn't back your data up to a server because there is no server. When you sync with someone else, you're talking directly to their device — no middleman, no cloud copies, no third party reading along.

Encrypted on disk

Your local databases are encrypted at rest. Identities, people, spaces, chats, tables — all stored in encrypted form on your disk. If someone else picks up your computer without your password, they can't just read your data straight out of the files.

Direct connections

When two Seamside devices talk, they connect directly to each other. Connections are authenticated: each side proves who it is before any real data crosses the wire. Visitors arriving via a share link see only what that link opens — a single frame, or a public space's read-only view — never the rest of your workspace.

Permissions are enforced on the host

Permissions (who can see a space, who can edit a table, who can operate a server) are checked on the device hosting the data, not just in the UI. Someone who loses access really does lose access — the UI and the backend agree, every time.

Deleting things

Deleting a contact, space, table, or frame removes it from your device. Anyone else who still has a copy keeps theirs — Seamside can't reach across the network and erase data from someone else's machine. If you need something gone from everywhere, you'll need to ask the other participants to delete their copies too. (This is the same trade-off that comes with any local-first system.)

In short

Your data lives on your devices, encrypted at rest.
You pick who connects to you.
What you share is what they see. What you don't share, they don't.

Now go make something

That's the whole handbook. Spaces hold your work, frames are your tools, people make it richer, tables make it persistent, and capabilities give your frames superpowers. The rest is yours to discover. Open a space, drop in a frame, and see what you make.