Bitskiff

Set up with a coding agent

On this page

This is the page a coding agent reads to set Bitskiff up. Give your agent the line on the home page; it reads the plain text at /setup.md.

You are helping a developer set up Bitskiff. Bitskiff connects a host to its clients, with data both ways in real time: the host opens a session, a client joins it from a device the person holds, and the two send messages on named channels. Do the whole setup from this one page. The person approves one sign-in and scans one code; everything else is yours.

Open a linked page only when a step needs it. Do not read ahead.

1. What this is for

At the end of this page the developer's own app has the Bitskiff SDK in its code, a project, a host key in bitskiff.json, and its first session: their host open, one client joined from a device they hold, a press that reaches the host's handler, and the host's reply shown on that client. The sample client page plays the client, so they need no client code and no client key yet.

Already set up? Run npx --yes https://docs.dev.bitskiff.com/downloads/0.3.0/bitskiff-cli.tgz doctor --format json in the project directory and go from what it reports: it checks the CLI build, the credential and where it came from, the project, the key's origins, the join URL and the api. Fix what it names, then go to step 5.

2. Read the app, ask only what it cannot tell you

Read the host's stack from the app: a browser page, or a Node program, from package.json and the files present. Only if you cannot tell, ask the person that one question, with your guess filled in so that they can reply "ok".

Ask nothing else. Do not ask for a key, a project name or an organization: the CLI and doctor answer those. Each app directory gets its own project, made by init and named for the directory.

Only want to see it work first? The sample host runs in a browser with no code and no account.

3. Get access

Use the first that works. Everything you do after it runs under the stored credential, with no further step from the person.

  1. A stored CLI credential. Run npx --yes https://docs.dev.bitskiff.com/downloads/0.3.0/bitskiff-cli.tgz whoami (Node 22 or newer). If its credential row names a key, you have access: go to step 4.
  2. A CLI sign-in. Run npx --yes https://docs.dev.bitskiff.com/downloads/0.3.0/bitskiff-cli.tgz init --no-wait --format json. It prints { verificationUri, userCode, expiresAt, next } and exits. Show the person the URL and the code, and ask them to open the URL and press Approve. Do not open it yourself: only a signed-in person can approve. Then run next through the same npx --yes https://docs.dev.bitskiff.com/downloads/0.3.0/bitskiff-cli.tgz in place of bitskiff: it waits for the approval and finishes step 4's init. A first-time person signs in on the way at the console.
  3. A key in the environment. If the person cannot sign in from this machine, they create an organization key in the console and set it as BITSKIFF_ORG_KEY in the environment you run in. The CLI reads it from there.

Never take a key in the chat. If the person pastes one, do not use it: tell them it is exposed, to revoke it in the console, and to give you access by 1, 2 or 3 instead.

Working through an MCP client rather than a shell? Add the CLI as a stdio MCP server, { "mcpServers": { "bitskiff": { "command": "npx", "args": ["--yes", "https://docs.dev.bitskiff.com/downloads/0.3.0/bitskiff-cli.tgz", "mcp"] } } }: every verb is a tool under the same stored credential.

4. Set it up

  1. Project and key. In the app's directory, run npx --yes https://docs.dev.bitskiff.com/downloads/0.3.0/bitskiff-cli.tgz init --format json. Pass no --project, and do not take one from whoami's project row: that row can name another app's project. If the directory has a bitskiff.json, init uses the project it names. If not, init makes a new project named for the directory, so a second app gets a second project. Either way it makes a host key and writes bitskiff.json (key, project, endpoint). Every later command run in that directory takes its project from that file. It prints no key string. In an existing app bitskiff.json is the one file it adds. The CLI reference has every flag.
  2. The host. Add the host code for the stack from step 2, reading the key from bitskiff.json. Declare the channels, listen, then open: a press channel whose handler answers on a readout channel to the client that pressed. A browser page follows the quickstart, steps 2 and 3. A Node program follows Node hosts.
  3. Open the session. Run the host. It shows a join code: its QR, and session.joinCode.url. A browser page served from http://localhost or http://127.0.0.1 on any port needs no origin set on the key.

5. Test it

  1. Show the person the join code's QR, or its URL, and ask them to scan it with the device they hold. It opens the sample client page, which needs no key.
  2. Ask them to press once. The press reaches the host's press handler, and the host's reply shows on their device.
  3. Read the session back with npx --yes https://docs.dev.bitskiff.com/downloads/0.3.0/bitskiff-cli.tgz sessions get <sessionId> --format json until its participants hold a client (an entry whose opener is false). The host's handler is your proof of the press; the person's device is the proof of the reply.

If the client does not join, run doctor and fix what it names.

6. Report

End with one short report, in this shape:

  • Made: the organization, the project and the host key, by name and id (never the key string), bitskiff.json, the host code's files, and the session id with its page in the console.
  • Works: the client that joined and the message each way.
  • Still the person's: what only they can do, for example an origin on the key for a deployed page, or a client page of their own (init --join-url <url>, Client pages).
  • Next: at most two steps, for example Channels for more messages, or a client page of their own.

Never put a key string in the report. If the person pasted a key at any point, remind them to revoke it.