small: deploy to Railway in one command

Русская версия

small deploys small team apps to Railway in one command and protects them with sign-in by work account (Google, Microsoft), work email or personal invite links.

small init my-service    # skeleton: invite-link protected server, small.json, .gitignore
cd my-service
small deploy             # → https://my-service-3f9a.up.railway.app
small open               # open with the invite link
small access add ivan@company.com   # who may sign in, like sharing a Google Doc
small sso google         # "Sign in with Google" (or small sso microsoft)
small mail resend        # or sign-in links by email
small access log         # who signed in, when and how
small access add bob     # or a personal link for bob (small access revoke bob to revoke it)
small notify telegram    # access requests to Telegram
small env set DEBUG=1    # environment variable in Railway and small.json
small db add postgres    # database, DATABASE_URL in the app
small volume add         # persistent disk: files and sign-in state survive deploys
small domain add app.example.com   # custom domain
small sleep on           # sleep when idle (saves money)
small logs -f            # app logs
small dashboard          # all apps in the browser: status, cost, logs
small destroy            # remove from Railway together with databases

You can also deploy an existing code folder (app.py, main.py, package.json and so on): small init is optional.

Python 3.9+, no dependencies.

Install

pip install small-software

The command is small. With pipx: pipx install small-software.

From source, in a clone of the repository:

pip install ./small-cli

Windows (recommended): one command in PowerShell.

irm https://raw.githubusercontent.com/RuslanKazyradzi13/small-software/main/install.ps1 | iex

It installs small into its own Python environment in %LOCALAPPDATA%\Programs\small and adds a small command that Smart App Control does not block (there is no unsigned small.exe). Needs Python 3.9+, no admin rights; run it again to upgrade. Uninstall:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/RuslanKazyradzi13/small-software/main/install.ps1))) -Uninstall

Values with & or | (URLs, for example) need PowerShell's stop-parsing token: small --% env set "URL=https://x?a=1&b=2".

Windows with pip. pip install creates small.exe, which Smart App Control / Application Control may block because it is unsigned. If that happens, either:

• run small through Python, which works everywhere: python -m small_cli deploy (any command works this way);
• or add the small-cli folder of a clone to PATH, and small.cmd will serve the small command. Run this in the root of the cloned repository ($PWD expands to its path), then open a new terminal:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$PWD\small-cli", "User")

Language

small speaks English and Russian. It uses Russian when the system language is Russian (LC_ALL, LC_MESSAGES, LANG, LANGUAGE, or the Windows display language) and English otherwise. To choose explicitly, set SMALL_LANG to en or ru:

export SMALL_LANG=en

$env:SMALL_LANG = "en"

Deployed apps pick their language separately:

• Sign-in pages and emails follow each visitor's browser language. ACCESS_LANG=ru or ACCESS_LANG=en forces one language.
• App log lines and Telegram notifications are for the owner and follow OWNER_LANG=en|ru. small deploy sets OWNER_LANG to small's own language unless small.json sets it. It does this only when small.json has at least one variable in env (apps created by small init always do); an app with an empty env gets no variables from small deploy at all.

Token

You need an account token or a workspace token (Railway → Account Settings → Tokens). A project token will not work: it cannot create projects.

Save the token to the RAILWAY_API_TOKEN variable, replacing YOUR_TOKEN entirely. Only the token itself, in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, should remain inside the quotes:

[Environment]::SetEnvironmentVariable("RAILWAY_API_TOKEN", "YOUR_TOKEN", "User")  # permanently
$env:RAILWAY_API_TOKEN = "YOUR_TOKEN"                                          # this terminal only

On macOS / Linux:

export RAILWAY_API_TOKEN="YOUR_TOKEN"   # add this line to ~/.bashrc or ~/.zshrc to keep it

A variable saved "permanently" is visible to new terminal windows. Terminals and apps that are already open do not see it; restart them. small strips spaces, quotes and angle brackets around the token by itself.

Fallback variable name: RAILWAY_TOKEN.

small init: app skeleton

small init [folder] [--template python-http|node-http|fastapi|streamlit] [--name NAME] [--force]

Creates a ready-to-deploy micro-app in the folder (the current one by default; created if it does not exist). --template (short: -t) picks the template, python-http by default:

The sample apps are in English: both the page text and the code comments.

• Invite-link protection. Templates are protected from the start, based on magic-link. small deploy passes ACCESS_TOKEN from small.json to Railway. The app opens at https://<domain>/?token=<ACCESS_TOKEN>; without the token visitors get a 403 page with a Request access button. The server listens on $HOST:$PORT, by default 0.0.0.0 and the PORT set by Railway.
• The streamlit template. Streamlit can't be wrapped in middleware, so require_access() in app.py uses MagicLinkGate from magic_link.py: the same variables (ACCESS_EMAILS, ACCESS_TOKEN, SESSION_SECRET, ACCESS_REQUEST_URL...), one-time links, limits and logs as the other templates, and the access screen follows the visitor's browser language. Differences:
  • Sign-in by email: the link leads to https://<domain>/?t=... and shows a Sign in button; only the click signs in. The 30-day session is a signed cookie written by a tiny same-origin frame, so unlike in the other templates it is not HttpOnly: don't render untrusted HTML in a protected app. Sign out is in the sidebar.
  • Personal links keep the token in the address bar (?token=), which is how they survive a page reload.
  • Streamlit is a single-page app, so the "no access" screen is served with HTTP 200, not 403. Railway runs python app.py, and app.py restarts itself through streamlit run on $HOST:$PORT. Run it locally the same way: python app.py.
• Name. By default, the folder name plus a random suffix, for example my-service-3f9a. An explicit name in small.json binds deploys to the Railway project with the same name, so the name must not accidentally match someone else's project. The suffix also makes it more likely that the <name>.up.railway.app subdomain is free. --name sets a name without the suffix.
• small.json is added to .gitignore because it holds the token. Do not publish it.

Existing files are not overwritten. If the folder already has files the template creates:

• in a terminal, small init lists them and asks Overwrite? [y/N];
• without a terminal (script, CI), the command fails. Either way, if you decline, nothing in the folder changes.

--force overwrites without asking, including small.json: you get a new name and a new ACCESS_TOKEN, and old invite links stop working after the next deploy. .gitignore and .railwayignore are never overwritten: only missing lines are appended, so running init again does not duplicate anything.

small dashboard: all apps in the browser

small dashboard [folder] [--port N] [--no-browser]

Starts a local server and opens a browser with all micro-apps in a folder: the current one by default, or any other, for example small dashboard ... An app is a folder with small.json and/or .small.json.

For each app the dashboard shows:

• name: from small.json, otherwise from .small.json, otherwise the folder name;
• status: Linked to Railway (.small.json has a service ID) or Not deployed;
• live status of the latest deploy from Railway (SUCCESS, BUILDING, FAILED, CRASHED…), if a token is set;
• auto-sleep: sleep mode is on (small sleep on);
• cost estimate in $/month at the current load (see below), with the total for all apps in the summary line;
• the public URL and a link to the service in the Railway console, if the app has been deployed;
• the folder path;
• names of the variables from small.json, without values;
• errors in small.json / .small.json: the same checks as small deploy runs.

The Refresh button rescans the folders without a restart. Stop the server with Ctrl+C.

Buttons on the card of a deployed app:

• Open via invite link opens the app right away with the owner's token, skipping the "invite only" screen. The token only goes to the browser's address bar on navigation; it is not in the dashboard page data.

• Logs opens a window with the last 200 lines of the app or build log (tabs App / Build). Requires RAILWAY_API_TOKEN; without it the button is disabled.

• Share opens who has access: work emails, whole domains and personal-link names (never the links themselves). Type ivan@company.com, @company.com or a name and click Add, or click Revoke next to anyone. It does exactly what small access add / revoke does: updates small.json and Railway and restarts the app. A new personal link is shown only once, with a Copy button, and works like a password. Requires RAILWAY_API_TOKEN. The page and its requests are protected: a per-run key, Host/Origin checks, no framing, JSON only.

• Port 3000 by default; if it is busy, any free port is used. The URL is printed to stdout.

• The server listens on 127.0.0.1 only and answers 403 to requests with a foreign Host (DNS rebinding protection). Values of the variables from small.json are never served: they include ACCESS_TOKEN.

• Search goes up to 6 levels deep. .git, node_modules, __pycache__, .venv and venv are skipped, and the scanner does not descend into an app it has found.

• Styles are loaded from the Tailwind CDN; without internet access the page works, just unstyled.

Live deploy statuses

If RAILWAY_API_TOKEN (or RAILWAY_TOKEN) is set at startup, on every refresh the dashboard asks Railway for the latest deploy of each linked app with the serviceInstance(serviceId, environmentId) { latestDeployment } query. The status is shown as a colored badge:

The badge tooltip shows the deploy time.

• Without a token the dashboard works offline from local files and never calls Railway.
• Errors (no network, the 5 s timeout, a wrong token, a deleted service) do not crash the server: those cards simply stay without a live status, and the summary line notes that Railway didn't respond.
• Speed. Requests run in parallel, so even a slow Railway delays a refresh by no more than the timeout.
• Security. The Railway token stays in the dashboard process and is never sent to the browser.

Cost estimate

The dashboard takes the project's load measurements for the past week from Railway (the metrics query: average CPU cores, GB of memory and GB of volumes per hour, including the app's databases) and multiplies the average load by the monthly prices from the Railway docs: $20 per vCPU, $10 per GB of memory, $0.15 per GB of volume. The result reads "≈ $X/mo at current load".

• Sleep and new apps. Hours when the app was asleep (small sleep) count as zero. For a new app the average starts at its first measurement, so the estimate is not understated.
• Why not usage. The accumulated usage arrives with a delay. In a live check it differed from the actual measurements by 7–50×, and differently for CPU and memory, so an honest total cannot be computed from it.
• This is an estimate, not a bill. Egress ($0.05/GB), the plan's free allowance ($5 on Hobby, $20 on Pro) and the subscription are not included. The exact amount is in Railway → Usage.

small mcp: AI agents (Claude Code, Cursor...)

small mcp

Runs an MCP server on stdin/stdout, so an AI coding agent can create, deploy and share apps itself: "Deploy this folder and give ivan@company.com access."

Connect it:

• Claude Code: claude mcp add small -- small mcp (Windows: claude mcp add small -- cmd /c small mcp).

• Cursor (~/.cursor/mcp.json), Claude Desktop, Windsurf and other clients:

  {"mcpServers": {"small": {"command": "small", "args": ["mcp"]}}}
  

  On Windows use "command": "cmd", "args": ["/c", "small", "mcp"], or "command": "python", "args": ["-m", "small_cli", "mcp"] if small was installed with pip.

• RAILWAY_API_TOKEN must be in the environment the agent starts from. After setting it, restart the agent.

Tools:

• No delete tool: small destroy stays a terminal command.
• Prefer emails. A personal link (a name instead of an email) is returned to the agent, so it passes through the chat like any other text; with email sign-in nothing secret does.
• The tools run the same code as the commands and answer in small's language (SMALL_LANG). Your MCP client normally asks you before each tool call.

small deploy

small deploy [folder] [--name NAME] [--workspace ID] [--port N] [-m MESSAGE] [--public] [--new] [--no-wait] [--timeout SEC]

Progress goes to stderr and the final URL to stdout: URL=$(small deploy). Exit codes: 0 success, 1 error or failed build (the last log lines are printed), 130 interrupted.

small gateway: sign-in in front of any app

small gateway [on [--port N] | off [--yes]]          # no subcommand: the status

The gateway protects an app that has no sign-in of its own — any language, any framework, a Dockerfile — without changing its code. It is a second service in the app's Railway project, <app>-gateway: Caddy takes every request, and magic-link next to it decides who gets in (Google and Microsoft sign-on, email links, invite links, all small access / small sso / small mail settings). Requests it lets in go on to the app over Railway's private network; the app itself has no public address.

• Private by default. The first small deploy of a folder without magic_link.py / magic-link.js sets the gateway up before the app ever gets an address, and puts your own invite link in small.json (small open). small deploy --public deploys such an app open to anyone instead; redeploying an app that is open prints a warning.
• on for an app already deployed: creates the gateway, moves the sign-in variables to it, moves the address (keeping its name), and restarts the app without a public address. The app must listen on $PORT (small sets it to 8080 if it isn't set) or pass --port. A custom domain has to be removed first and added back after; it then points to the gateway.
• Who is signed in. The gateway adds X-Small-User (the address, or the invite-link name), X-Small-Method (email, google, microsoft, link) and X-Small-Auth, an HMAC signature of both with SMALL_GATEWAY_KEY, which the app gets as a Railway reference. Any X-Small-* header a visitor sends is dropped. magic-link in the app (0.9+) trusts that signature and nothing else, so an app that keeps its own sign-in code works behind the gateway too.
• Websockets go through the same check. For Streamlit this means an HttpOnly session cookie set by the gateway.
• Where things live. Sign-in variables (ACCESS_*, SESSION_SECRET, GOOGLE_*, MICROSOFT_*, SESSIONS_REVOKED…) belong to the gateway; mail and Telegram variables go to both; everything else stays the app's. small env, small access, small sso, small mail and small deploy route them for you, and restart only the service that changed.
• The rest follows: small access log reads the gateway's log, small logs --gateway shows it, small sleep puts both to sleep (the first request wakes both, a few seconds), small domain attaches to the gateway, small volume add --gateway keeps sign-in state across the gateway's restarts, small destroy removes both.
• small deploy also rebuilds the gateway when it was built by an older small.
• off gives the address and the variables back to the app and deletes the gateway. If the app has no sign-in of its own, small asks first (or --yes): without the gateway anyone with the address gets in.
• Cost: one more small service. Caddy and the sign-in server idle at a few tens of MB; with sleep on, both sleep.

After deploy

These commands work in the folder of a deployed app, that is, where .small.json is. link, open, logs and destroy take the path as an argument; the others take it as -C folder.

small link [folder] [--as NAME]                       # print the invite link
small open [folder] [--as NAME]                       # the same + open it in the browser
small access [list | add EMAIL|@DOMAIN|NAME | revoke EMAIL|NAME]   # who can sign in
small access log [-n N] [--json]                   # who signed in, when and how
small access signout EMAIL|@DOMAIN|--all           # end their sessions on all devices
small sso [google [--client-id ID] | microsoft [--client-id ID] [--tenant T] | off [PROVIDER]]
small mail [resend | smtp [--from FROM] [--to TO] | log | off]  # emails for sign-in by email
small notify [telegram [--chat-id ID] | off]        # access requests to Telegram
small env [list [--values] | set K=V ... | unset K ...] [--no-deploy]
small db [list | add postgres | remove postgres [--yes]]
small volume [add [--mount /data]] [--gateway]      # persistent disk; no argument shows the status
small gateway [on [--port N] | off [--yes]]          # sign-in in front of any app (see above)
small domain [list | add DOMAIN [--port N] | remove DOMAIN]
small sleep [on | off]                              # sleep mode; no argument shows the status
small logs [folder] [--build | --gateway] [-n N] [-f]  # log of the latest deploy
small destroy [folder] [--yes]                       # remove from Railway

Commands that change the app's variables (access add / revoke / signout, sso, mail, notify, env set / unset, db add / remove), volume add and sleep on / off restart the app once. Add --no-deploy to skip the restart; the change then takes effect on the next deploy.

small link / small open build https://<domain>/?token=<token>.

• Where the token comes from. From small.json, or, if it is not there (for example, the token was set in the Railway dashboard), from the service variables in Railway; that requires RAILWAY_API_TOKEN. Without --as the first token (the owner's) is used; --as bob gives bob's personal token.
• If there is no token anywhere, the address is printed without a token.
• Output. The link goes to stdout, so you can pass it on: small link | clip. It works like a password, so send it only to people who need access.

small access controls who can open the app. There are two ways, and you can combine them.

By address, like sharing a Google Doc. This is the recommended way:

• add ivan@company.com adds the address to ACCESS_EMAILS. Ivan opens the app and proves the address is his: with Sign in with Google / Microsoft (small sso), or by entering it and getting a sign-in link by email (small mail) that works for 15 minutes and only once. The browser remembers the sign-in for 30 days. Passing a link on gives nobody anything: only the owner of the mailbox or account gets in.
• add @company.com lets in everyone with an address in that domain.
• revoke ivan@company.com closes sign-in right after the restart, even in a browser that is already open. The time also goes to SESSIONS_REVOKED, so if you add the address back later, the old sessions stay invalid.
• signout ivan@company.com (or @company.com, or --all) ends the sessions on every device without taking access away: for a lost laptop. People can do it themselves with Sign out on all devices if the app has a volume (small volume add).
• log prints who signed in, when, how (Google, Microsoft, email link, invite link) and from which IP, plus refused sign-ins and access requests, across deploys: magic_link writes them as JSON log lines, and Railway keeps them as long as your plan keeps logs. --json gives one object per line.
• The first add creates SESSION_SECRET, the key that signs links and sessions. One way to sign in must be set up: small sso or small mail.
• small passes the address for links in emails to the app itself, in PUBLIC_URL (in Railway only): after the domain is renamed to <name>.up.railway.app, Railway keeps the old address in RAILWAY_PUBLIC_DOMAIN, and the links would lead to a 404. If you want links on your own domain, set PUBLIC_URL in small.json; small does not touch it.
• Someone who is not on the list and enters their email gets the same "Check your email" response, and the owner receives an access request (in the log, and in Telegram if connected) with a ready-made small access add their@address command.
• Works in all templates: python-http, fastapi, node-http and streamlit (see the streamlit notes above).

By personal invite link:

• add bob creates a token, adds it to ACCESS_TOKEN as bob:token, restarts the app and prints the link. The link works like a password: anyone it is forwarded to can get in.

• revoke bob: after the restart neither bob's link nor the cookie he already has works; everyone else keeps their access.

• list shows who has access: addresses and names (tokens are hidden).

• Sign-in log. small access log (above). In the raw log (small logs) each sign-in is one JSON line, for example {"message": "[magic-link] signed in with Google: ivan@company.com, ip 203.0.113.7", "magic_link": "sign_in", "method": "google", ...}; Railway's log explorer filters them with @magic_link:sign_in.

small sso sets up sign-in with a work account. Who may sign in is still the access list.

• google: "Sign in with Google" for Google Workspace accounts and Gmail addresses. small prints what to do in Google Cloud (about 5 minutes: an OAuth client of type Web application) and the exact redirect URI to register, then asks for the client ID and secret (the secret from GOOGLE_CLIENT_SECRET or with hidden input).
• microsoft: "Sign in with Microsoft" for the members of one Microsoft Entra organization. small prints the steps (an app registration, single tenant, a client secret) and the redirect URI; --tenant takes the Directory (tenant) ID or your domain (company.com), which small resolves to the ID.
• Checked before saving. small shows the provider the client ID and secret; a wrong pair is refused and nothing is saved.
• Which accounts count. Google: verified Gmail addresses, or accounts of a Google Workspace organization; a personal Google account registered with a company address is refused. Microsoft: members of your tenant only, not guests and not other organizations. Details: SECURITY.md.
• Redirect URI: https://<app>/_access/sso/callback, or https://<app>/ for streamlit. With your own domain, set PUBLIC_URL in small.json first, and register that address.
• If email sign-in isn't set up, the sign-in page shows only the provider buttons; with both, it shows both.
• off [google|microsoft] turns one or both off; with no subcommand you get the status and the redirect URI.

small mail sets how the app sends sign-in emails.

• resend sends through Resend over HTTPS. small takes the key from RESEND_API_KEY or asks for it with hidden input. Railway's Hobby plan blocks SMTP ports, so on Hobby this is the main option (Railway docs). Without a domain verified in Resend, emails go only to your Resend account's address; for colleagues, verify a domain and pass --from "Reports <noreply@company.com>".
• smtp uses your own mail server: SMTP_URL in the form smtp://user:password@server:587 (or smtps://…:465), taken from the environment or asked for with hidden input. On Railway it works from the Pro plan.
• Before saving, resend and smtp send a test email (--to address) with the same code the app uses. If it does not go through, nothing is saved and the reason is printed. --from and --to work with both.
• log writes the sign-in link to the app log instead of sending an email. For testing only: a link from the log lets you into the app.
• off turns email off; with no subcommand you get the status (resend, smtp, log or off).

small notify sends access requests to the owner in Telegram.

• telegram connects a bot. Create one with @BotFather (/newbot). small takes the bot token from TELEGRAM_BOT_TOKEN or asks for it with hidden input, so it does not end up in your terminal history. Then small asks you to send the bot any message, finds the chat ID itself, sends a test notification and writes TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID to Railway and small.json. You can pass the chat ID right away with --chat-id.
• What a notification looks like. When someone clicks Request access and leaves a contact, you get a message with the app's address, the contact, the IP and a hint: small access add NAME. Works in all templates (python-http, fastapi, node-http, streamlit) and in magic-link in general. The request is still written to the log as well.
• off disconnects the bot; with no subcommand you get the status.

small db adds a database in one step.

• add postgres deploys Postgres from the Railway template (like railway add --database postgres) into the app's project and passes DATABASE_URL to the app as the Railway reference ${{Postgres.DATABASE_URL}}. The password is stored only in Railway; small.json gets just the reference. The app reaches the database over Railway's private network.
• Startup. The database takes about a minute to start: if the app connects to it at startup, the first start may happen before the database is ready.
• list shows the app's databases and their status.
• remove postgres deletes the database together with its data (confirm by typing the name, or pass --yes) and removes DATABASE_URL.
• small destroy deletes the databases together with the app.

small domain sets up a custom domain instead of *.up.railway.app.

• add app.example.com registers the domain in Railway and prints the DNS records for your registrar: a CNAME pointing to the Railway address and, if Railway asks for it, a TXT record that verifies ownership.
• Certificate. Once the records are live (from minutes to a day), Railway issues the HTTPS certificate by itself.
• Invite links work on the custom domain too: https://app.example.com/?token=….
• list shows the domains and their state (waiting for DNS records / DNS configured) and the certificate status.
• remove removes the domain.

small volume gives the app a persistent disk (a Railway volume).

• add creates one at /data (--mount for another path, outside /app) and restarts the app. The app can keep files there; the path is in RAILWAY_VOLUME_MOUNT_PATH. With no subcommand you get the path and how much is used.
• Sign-in state. magic_link keeps it in .magic-link.db (SQLite) on the volume: used sign-in links stay used after a restart, rate limits are shared by worker processes, and Sign out on all devices appears. Without a volume this state lives in memory and a restart forgets it.
• Trade-off. With a volume each deploy has a few seconds of downtime: two copies of the app can't share the disk. A service has one volume.

small sleep controls Railway's sleep mode (serverless).

• on: with no incoming requests the app goes to sleep and uses no CPU or memory; the first request wakes it up in a few seconds. Handy for apps that are opened a couple of times a day.
• off: the app always runs. With no argument you get the current mode.
• Restart. The setting takes effect after a restart, which small sleep does by itself (--no-deploy postpones it until the next deploy).

small env manages the app's environment variables.

• list shows the variables and where they are set: small.json + Railway, Railway only, or Railway ≠ small.json. Values are hidden; --values shows them. Internal RAILWAY_* variables are not listed.
• set / unset change variables in both Railway and small.json at once; otherwise the next small deploy would bring back the old values. After a change Railway restarts the app once; --no-deploy turns that off. If the app has not been deployed yet, only small.json changes.
• Removed variables. If you removed a variable from small.json by hand, delete it with small env unset so that it disappears from Railway too.

small logs shows the log of the latest deploy.

• Which log. The app log by default, the build log with --build, the gateway's with --gateway. -n sets the number of lines (default 100).
• Follow mode. -f appends new lines every 2 seconds; Ctrl+C exits.
• Format. Every line is printed with its local time. Requests from the Request access button show up as [access-request] ..., and they are easy to filter: small logs | findstr access-request.
• Limitation. -f follows the deploy that was the latest when the command started; after a new deploy, run the command again.

small destroy removes the app from Railway.

• What gets deleted. If the project contains only this app's services (the service itself and the databases from small db), the whole project is deleted: services, domains, variables, deploys, database data. If small deploy once linked the folder to a project that also has other services, only the app's services are deleted and the rest stay.
• Confirmation. In a terminal you have to type the project name. Without a terminal (script, CI) the app is deleted only with the --yes flag. If you decline, nothing is deleted.
• Local files. After the deletion .small.json is removed, while small.json stays, so the next small deploy creates a new project with the same settings.

Settings: small.json

An optional file in the root of the app folder:

{
  "name": "my-custom-app-name",
  "env": {
    "OPENAI_API_KEY": "sk-...",
    "DEBUG": "true"
  }
}

Both fields are optional; any other field is an error (this catches typos like "envs"). An error in the file stops the deploy before any request to Railway.

Name. While the folder is not linked to a service (there is no .small.json), an explicitly set name (from small.json or --name) works as an identifier: if Railway already has a project with that name, for example after a deploy from another computer, small connects to it instead of creating a duplicate. If there is no such project, it is created. If there are several projects with that name, the deploy stops with an error. --new always creates a new project. If the folder is already linked, a new name is not applied, and small warns you about it. To link the folder to another project, delete .small.json.

Variables are written on every small deploy, before the code is uploaded, so the new build sees them right away. small uses variableCollectionUpsert, the batch form of variableUpsert, with replace: false: variables from env are added or updated, and the service's other variables (for example, an ACCESS_TOKEN set in the dashboard) are left alone. A variable removed from env stays in Railway: delete it with small env unset or in the dashboard (service → Variables). Only variable names are printed, never values.

Unless env sets them itself, small deploy also passes the app PUBLIC_URL (when sign-in by email is on, see small access) and OWNER_LANG (small's language, see "Language" above). With an empty env, small deploy writes no variables at all, OWNER_LANG included.

Secrets. The root small.json is not uploaded to Railway with the code. If it holds keys, add it to .gitignore so that it does not end up in git.

small.json and .small.json are different files. You write the first one yourself (settings). small creates the second one: it holds the project and service IDs and the domain.

Under the hood

1. small.json is read and validated, if it exists.
2. The folder's code is packed into a .tar.gz. The root .gitignore and .railwayignore are respected; .git, node_modules, __pycache__, .venv, venv, as well as small.json and .small.json in the root, are always excluded.
3. GraphQL at https://backboard.railway.com/graphql/v2: me.workspaces (picking the workspace). If the name is set explicitly, projects looks for a project with that name. Then projectCreate and serviceCreate, if there is no matching project.
4. serviceDomainCreate creates a *.up.railway.app domain. If <name>.up.railway.app is free (serviceDomainAvailable), the domain is renamed to it (serviceDomainUpdate). If the name is taken, the domain Railway assigned stays. If the service was found by name and already has a domain, the existing one is used. The domain is created before the upload because the very first build needs its address (links in sign-in emails).
5. variableCollectionUpsert writes the variables from small.json, plus PUBLIC_URL and OWNER_LANG (see above). With an empty env this step is skipped.
6. The archive goes to POST https://backboard.railway.com/project/{projectId}/environment/{environmentId}/up?serviceId=.... This is the same endpoint the official railway up uses. It starts the build and returns a deploymentId.
7. deployment(id) { status } is polled every 3 s until SUCCESS (or SLEEPING) or a failure status: FAILED, CRASHED, REMOVED, REMOVING, SKIPPED, NEEDS_APPROVAL. On FAILED the buildLogs are printed, on any other failure the deploymentLogs.
8. https://<domain> is printed.

The project and service IDs and the domain are saved to .small.json in the app folder. The next small deploy ships a new version to the same service and does not create a new project. The file is written right after the project is created or linked, so a failed build does not spawn extra projects when you retry.

The build is done by Railpack, which detects the language by itself. For Python, app.py or main.py is enough (plus requirements.txt for dependencies), and the start command will be python app.py. The app must listen on 0.0.0.0:$PORT.

Tests

In the small-cli folder of a clone:

python -m unittest discover -s tests

The tests start a local mock of the Railway API (GraphQL + the upload endpoint) and run the full scenario: first deploy, repeat deploy, failed build, crash, taken domain, several workspaces, wrong token, ignore rules.

Template tests on real frameworks are skipped if the framework is not installed; the rest pass.

• streamlit tests: the access gate through streamlit.testing.v1.AppTest (personal tokens, sign-in by email: form, one-time link, session cookie, revocation, sign out; sign-in with Google against a local provider, refusals, sign out on all devices) and the server through python app.py.
• 2 fastapi tests: TestClient and uvicorn main:app the way Railway runs it, plus a check that the token is hidden in the access log.

small env and small access are tested against the Railway mock:

• variable sources and hidden values;
• set / unset together with small.json, a single restart, --no-deploy;
• before the first deploy;
• a Railway failure that leaves small.json unchanged;
• granting, revoking and link --as, revoking the last token, a token that exists only in Railway.

Dashboard buttons: the "Open via invite link" redirect and its protection against foreign paths, "Logs" without a token, with Railway and with Railway unavailable. Sleep mode and the cost estimate in the dashboard, Railway errors while computing the cost.

small sso, volume, access log and access signout are tested against mocks of Railway, Google and Microsoft: the credential check, a wrong secret that saves nothing, resolving a domain to a tenant, the Streamlit and custom domain redirect URIs, old magic_link code, the volume and its mount path, the access log table, --json and the MCP tool, sign-outs by address, domain and --all, forgetting old sign-outs.

small sleep, db, domain and notify are tested against mocks of Railway and the Telegram Bot API:

• turning sleep on and off, turning it on again without requests, --no-deploy;
• deploying the Postgres template with default values, the DATABASE_URL reference, a workflow error, removing the database, destroy together with the database;
• DNS records for a custom domain, address normalization, repeat and removal;
• finding the bot's chat, the test message, a wrong token, "nobody messaged the bot", a missing token.

small init is tested like this (the streamlit template too):

• the python-http and node-http templates and unique names and tokens (fastapi and streamlit have their own tests, see above);
• protection of existing files: declining, --force, the terminal prompt;
• appending to .gitignore without duplicates;
• the init → deploy chain;
• python-http and node-http run as real servers (403 → link → cookie → 200);
• the copies of magic_link.py and magic-link.js in the templates match the sources in the repository's magic-link/ folder.

small dashboard is tested like this (live statuses against the Railway mock: success, partial failure, no network, timeout, wrong token, garbage status, no token in the response):

• scanning: nested folders, service folders, folders inside an app, the depth limit, an app at the root;
• app descriptions and no variable values in the output;
• broken files and unsafe links;
• the page and the API, including a rescan;
• 403 for a foreign Host;
• the fallback port;
• the command itself: URL, browser, --no-browser.

small.json is tested separately:

• name and variables, the "variables before upload" order;
• excluding the file from the archive;
• linking to an existing project and an ambiguous name;
• --new and the precedence of --name;
• an already linked folder and an invalid file.

SMALL_API_URL overrides the API address.

Limitations

• Only the root .gitignore/.railwayignore are read; nested ones are ignored.
• One service is created (two with the gateway), in the production environment. Databases: Postgres only (small db).