1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
.Dd April 14, 2026
.Dt ASCIINEMA-SERVER 1
.Os
.Sh NAME
.Nm asciinema-server
.Nd minimal self-hosted asciinema recording server
.Sh SYNOPSIS
.Nm
.Nm
.Cm create-invite
.Fl username Ar name
.Nm
.Cm delete-user
.Fl username Ar name
.Nm
.Cm reset-password
.Fl username Ar name
.Sh DESCRIPTION
.Nm
is a minimal self-hosted server compatible with the
.Xr asciinema 1
CLI client. It accepts terminal recording uploads, stores them in a
SQLite database, and serves a browser playback page for each recording.
.Pp
All data \(em recordings, users, sessions, and invites \(em lives in a
single SQLite database file. Recordings are stored as zstd-compressed
blobs directly in the database.
.Pp
The server is configured entirely via environment variables:
.Bl -tag -width Ds
.It Ev DATABASE_PATH
Path to the SQLite database file.
Default:
.Pa asciinema.db .
.It Ev PORT
Port to listen on.
Default:
.Li 4000 .
.It Ev BASE_URL
Full public base URL used in links returned to the CLI, e.g.\&
.Li https://asciinema.example.com .
Default:
.Li http://localhost:<PORT> .
.It Ev UPLOAD_SIZE_LIMIT
Maximum upload size in bytes.
Default: 10485760 (10\~MB).
.El
.Sh SUBCOMMANDS
.Bl -tag -width Ds
.It Cm create-invite Fl username Ar 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.
.Pp
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.
.Pp
Reads
.Ev DATABASE_PATH
from the environment.
.It Cm delete-user Fl username Ar 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.
.Pp
Reads
.Ev DATABASE_PATH
from the environment.
.It Cm reset-password Fl username Ar 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
.Pa /connect/<install_id>
and uses it to set a new password.
.Pp
Reads
.Ev DATABASE_PATH
from the environment.
.El
.Sh USER REGISTRATION
There is no open registration. The server operator creates accounts
explicitly:
.Bl -enum
.It
Run
.Cm create-invite Fl username Ar 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.
.It
Share the token with the user out of band (e.g. over email or chat).
.It
The user runs
.Ic asciinema upload
or
.Ic asciinema auth ,
which prints a connect URL of the form:
.Pp
.D1 Pa http://example.com/connect/<install_id>
.It
The user visits that URL in a browser. The page shows a register form
(invite token + password) and a login form (username + password).
.It
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 \(em future uploads from that machine are
authenticated automatically.
.El
.Sh WEB INTERFACE
.Bl -tag -width Ds
.It Pa /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.
.It Pa /a/<secret_token>.cast
Raw
.Li application/x-asciicast
file download, decompressed on the fly.
.It Pa /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.
.It Pa /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.
.El
.Sh EXAMPLES
Run the server:
.Bd -literal -offset indent
$ DATABASE_PATH=./asciinema.db asciinema-server
.Ed
.Pp
Create an invite token for the first user:
.Bd -literal -offset indent
$ DATABASE_PATH=./asciinema.db \\
asciinema-server create-invite -username alice
Invite token for alice: 4f350a1986e7dcce5439fb49
.Ed
.Pp
Point the
.Xr asciinema 1
CLI at the server by adding to
.Pa ~/.config/asciinema/config :
.Bd -literal -offset indent
[api]
url = http://localhost:4000
.Ed
.Pp
Or set the environment variable for a single invocation:
.Bd -literal -offset indent
$ ASCIINEMA_API_URL=http://localhost:4000 asciinema upload recording.cast
.Ed
.Pp
If the CLI is not yet linked, the response message will include the
connect URL to visit in a browser.
.Pp
Delete a user and all their recordings:
.Bd -literal -offset indent
$ DATABASE_PATH=./asciinema.db \\
asciinema-server delete-user -username alice
Deleted user alice and 7 recording(s).
.Ed
.Sh SEE ALSO
.Xr asciinema 1 ,
.Xr sqlite3 1
.Pp
asciinema-player:
.Lk https://github.com/asciinema/asciinema-player
.Sh AUTHORS
.An Profpatsch
.Pp
.Nm
was created with
.An Claude Code .
|