Profpatsch/users/Profpatsch/asciinema-server

Impl of the asciinema server in golang

View full contents ↓

A Go reimplementation of asciinema-server by Marcin Kulik, licensed under Apache-2.0. Compatible with the asciinema CLI and player ecosystem — accepts recording uploads, serves playback, and relays live streams via the ALiS v1 protocol.

Run with go build or nix-build:

DATABASE_PATH=asciinema.db BASE_URL=http://localhost:4000 ./asciinema-server serve

Environment variables: DATABASE_PATH, BASE_URL, PORT, LISTEN_ADDR, APP_TITLE, UPLOAD_SIZE_LIMIT.

Commands: serve, create-invite, delete-user, reset-password.

Live streaming requires a linked account; use asciinema stream --remote with ASCIINEMA_API_URL pointing at this server.

asciinema-server(1)

asciinema-server - minimal self-hosted asciinema recording server

asciinema-server
asciinema-server create-invite -username name
asciinema-server delete-user -username name
asciinema-server reset-password -username name

asciinema-server is a minimal self-hosted server compatible with the asciinema(1) CLI client. It accepts terminal recording uploads, stores them in a SQLite database, and serves a browser playback page for each recording.

All data — recordings, users, sessions, and invites — lives in a single SQLite database file. Recordings are stored as zstd-compressed blobs directly in the database.

The server is configured entirely via environment variables:

DATABASE_PATH

Path to the SQLite database file. Default: asciinema.db.

PORT

Port to listen on. Default: 4000.

BASE_URL

Full public base URL used in links returned to the CLI, e.g. https://asciinema.example.com. Default: http://localhost:<PORT>.

UPLOAD_SIZE_LIMIT

Maximum upload size in bytes. Default: 10485760 (10 MB).

create-invite -username name

Create a single-use invite token for the given username and print it to stdout. The admin chooses the username; the user cannot change it. The admin runs this command and shares the token with the intended user out of band. There is no self-registration; every account must be created this way.

The invite token is a randomly generated hex string. It can only be used once: after a user claims it by setting a password on the connect page, it is marked used and cannot be reused.

Reads DATABASE_PATH from the environment.

delete-user -username name

Delete a user account and all associated data: recordings, sessions, CLI tokens, and the invite row (freeing the username for reuse). Prints the number of recordings deleted.

Reads DATABASE_PATH from the environment.

reset-password -username name

Reset a user's password. Clears the existing password hash (invalidating it immediately), removes any pending unused invite for that username, and generates a new single-use invite token. The admin shares the token with the user; the user visits /connect/<install_id> and uses it to set a new password.

Reads DATABASE_PATH from the environment.

There is no open registration. The server operator creates accounts explicitly:

  1. Run create-invite -username name to generate a token for the new user. The admin picks the username; the user will log in under this name and cannot change it.

  2. Share the token with the user out of band (e.g. over email or chat).

  3. The user runs asciinema upload or asciinema auth, which prints a connect URL of the form:

    http://example.com/connect/&lt;install_id>

  4. The user visits that URL in a browser. The page shows a register form (invite token + password) and a login form (username + password).

  5. The user enters the invite token and chooses a password. The server creates the account, links the CLI install-id to it, and sets a session cookie. The user is done — future uploads from that machine are authenticated automatically.

/a/<secret_token>

Browser playback page for a recording. Uses the embedded asciinema-player (Apache 2.0, copyright 2011-2021 Marcin Kulik). All recordings are access-controlled by their secret token; there are no public or unlisted visibility levels. The owner sees a delete button and a link to their recordings list.

/a/<secret_token>.cast

Raw application/x-asciicast file download, decompressed on the fly.

/connect/<install_id>

CLI linking page. Shows a register form (invite token + password) for new users and a login form (username + password) for existing users. After either action the CLI install-id is linked to the account and a session cookie is set. Subsequent visits by a logged-in user show a confirmation that the CLI is linked.

/user/my-recordings

Lists all recordings for the logged-in user: title, duration, date, and a delete button per row. Also contains a button to delete the account and all its recordings.

Run the server:

$ DATABASE_PATH=./asciinema.db asciinema-server

Create an invite token for the first user:

$ DATABASE_PATH=./asciinema.db \
    asciinema-server create-invite -username alice
Invite token for alice: 4f350a1986e7dcce5439fb49

Point the asciinema(1) CLI at the server by adding to ~/.config/asciinema/config:

[api]
url = http://localhost:4000

Or set the environment variable for a single invocation:

$ ASCIINEMA_API_URL=http://localhost:4000 asciinema upload recording.cast

If the CLI is not yet linked, the response message will include the connect URL to visit in a browser.

Delete a user and all their recordings:

$ DATABASE_PATH=./asciinema.db \
    asciinema-server delete-user -username alice
Deleted user alice and 7 recording(s).

asciinema(1), sqlite3(1)

asciinema-player: https://github.com/asciinema/asciinema-player

Profpatsch

asciinema-server was created with
Claude Code.