Install and requirements Guide 1 of 5
SmartDecision runs on a Linux server with Docker. One script installs it with your license key and starts it on port 8080.
Requirements
- A Linux server, amd64 or arm64.
- Root, or a user with
sudo. -
Docker with the compose plugin. If Docker is missing, the installer installs it. If the compose plugin is
missing, install the
docker-compose-pluginpackage and run the installer again. - Internet access to
get.smartdecision.iowhile you install or upgrade. - Port 8080 free on the server.
- Your license key, from your welcome email.
The app and the built-in AI run as separate containers. The app is small. The built-in AI needs more memory, but only while someone is drafting a decision: the model loads when you open New decision and unloads after 10 minutes without use. Resolving decisions never uses it.
| App only | With built-in AI (minimum) | With built-in AI (recommended) | |
|---|---|---|---|
| CPU | 1 vCPU | 2 vCPUs | 4 vCPUs |
| Memory | 512 MB | 8 GB | 16 GB |
| Storage | 1 GB | 8 GB | 18 GB |
| GPU | Not used | Not required | Not required |
"App only" also applies when you point SmartDecision at your own AI server, or run it without AI.
Without a GPU, drafting takes a while. On 4 vCPUs the model needs about a minute to get ready. It starts preparing when you open New decision, while you write the policy. Each draft then takes about 30 seconds, and up to a minute for longer policies. With fewer vCPUs it is slower.
Install
On the server, download the installer and run it:
curl -fsSL https://get.smartdecision.io/install.sh -o install.sh
sh install.sh The installer:
- Asks for your license key. Paste it from your welcome email.
- Asks how SmartDecision should draft decisions: the built-in AI, your own AI server, or no AI. See AI: built-in or your own.
- Checks Docker, and installs it if it is missing.
- Downloads the newest SmartDecision version your key covers, checks its checksum and loads it into Docker.
- With the built-in AI, downloads the model (about 2.5 GB). If the download stops, run the installer again and it resumes.
- Writes its configuration to
~/.smartdecisionand starts SmartDecision.
When it finishes, open http://<your-server>:8080 in a browser and go on to
First sign-in.
Unattended installs
Pass the answers as options and the installer asks nothing:
sh install.sh --license=SD1.your-key --llm=builtin | Option | What it does |
|---|---|
--key=KEY | Downloads with this license key. It is saved for later runs, and the app installs it on its first start. An admin can replace it in Settings. |
--license=KEY |
Same as --key, and also installs the key in the app as
SMARTDECISION_LICENSE. The key can then only be changed on the server. See
Entering a key.
|
--url=URL |
The address your apps and teammates use to reach SmartDecision, like
https://decisions.example.com. It is the start of the Resolve API endpoint in
Use in app and of invitation links. Without it, the installer uses this server's IP address on
port 8080. Admins can change it in Settings → Server address.
|
--llm=builtin|external|none | The AI choice: built-in AI, your own AI server, or no AI. |
--llm-url=URL | With --llm=external: the endpoint's base URL, for example http://gpu-box:11434/v1. |
--llm-model=NAME | With --llm=external: the model name to request. |
--llm-api-key=KEY | With --llm=external: an API key for the endpoint, if it needs one. |
--version=VERSION | Installs that version, like 1.4.0, instead of the newest one your key covers. |
Servers without internet access
On a machine that has internet access, open get.smartdecision.io
and paste your license key to download the image and install.sh. Email
support@smartdecision.io if you need help with an offline install.
What gets installed
SmartDecision runs as a Docker Compose project named smartdecision. Everything it keeps lives in
~/.smartdecision in the home directory of the user who ran the installer:
| Path | What it is |
|---|---|
local.db | The database: users, projects, decisions, tests, secret keys and the activity log. Back this up. |
all.log | The app's log file. The app writes its log here, not to docker logs. |
.env | Settings: the AI choice and endpoint, the license key and the server address. Readable by its owner only. |
compose.yaml | The Compose file for the two containers. |
llm-config.yaml | Configuration for the built-in AI. |
models/ | The built-in AI's model file, when you use it. |
images/ | Temporary space for downloads. It is emptied after each install. |
There are two services:
-
app(containersmartdecision): the web app and the Resolve API, published on port 8080. -
llm(containersmartdecision-llm): the built-in AI. It is in theaiCompose profile, so it runs only when you chose the built-in AI. It is not published on the host: only the app can reach it.
To manage the containers, run Compose from that directory:
cd ~/.smartdecision
sudo docker compose ps # what is running
sudo docker compose up -d # start, or apply changes to .env
sudo docker compose restart app # restart the app
sudo docker compose logs llm # the built-in AI's output
Running the installer again rewrites .env, compose.yaml and
llm-config.yaml. It keeps your license key, but asks the AI question again unless you pass
--llm. Don't customise compose.yaml or llm-config.yaml by hand.
The installer also adds a smartdecision command to your shell (open a new shell to use it). If you
lose the admin password, reset it with:
smartdecision admin cpass SmartDecision serves plain HTTP on port 8080. To serve it over HTTPS, put your own reverse proxy in front of it.
AI: built-in or your own
The AI only drafts decisions from policy text. Editing, testing and resolving work the same without it. You choose one of three options when you install, and you can switch by running the installer again.
Built-in AI
The installer downloads a pinned model, Qwen3-4B-Instruct-2507 (Q4_K_M, about 2.5 GB, Apache-2.0 license), to
~/.smartdecision/models, and turns on the ai Compose profile. The
llm container starts the model on the first request and stops it after 10 minutes idle, so the
memory is used only while someone is drafting. The model runs on your server and nothing is sent elsewhere.
Your own AI server
Point SmartDecision at your own AI server, for example Ollama, vLLM or llama.cpp's llama-server.
It must serve chat completions at /v1, the API these servers share, with structured outputs
(response_format of type json_schema), and accept temperature and
seed.
When you draft a decision, SmartDecision sends the policy text to this server. Run it inside your network to keep your data there. SmartDecision uses these settings:
-
LLM_URL: the base URL, including/v1. The app callsLLM_URL/chat/completionsto draft, andLLM_URL/modelsto check that the AI is available. LLM_MODEL: the model name sent with each request.LLM_API_KEY: sent asAuthorization: Bearer <key>when set.
The app runs in a container, so localhost in LLM_URL means the container itself. To
reach a server on the same host, use host.docker.internal instead, for example
http://host.docker.internal:11434/v1.
SmartDecision's drafting is tuned and tested against the built-in model. Other models can draft differently, so check their tables with tests.
No AI
The Describe a policy option is turned off. You start decisions from a template or from a blank table.
First sign-in
-
Open
http://<your-server>:8080and sign up. The first account becomes the admin. - The license key you gave the installer is already in place. An admin can replace it in Settings → License.
- Invite your team from Settings → Invite teammate. Each invitation is a link that works once and expires after 7 days. Everyone after the first account needs one to sign up.
Admins manage members, invitations and the license. Sign-ins last 72 hours. Pending invitations count toward your license's user limit.
Lost password
Passwords are reset on the server. Nobody can reset another account's password from inside the app, admins included, and teammates who joined by invitation are never admins. Whoever runs the server can set a new password for any account:
smartdecision reset-password --email anna@example.com
It asks for the new password twice (8 to 72 characters) and never takes it on the command line, so it stays
out of your shell history. Without --email it resets the admin account. The sign-in page shows
this command with the email already filled in.
smartdecision is a shortcut the installer adds to ~/.bashrc. In a new shell, or as
another user, run the same command through Docker:
sudo docker exec -it smartdecision /bin/smartdecision/cli reset-password --email anna@example.com Upgrading
Every release is included while your license is active. The changelog lists what changed in each one, and has an RSS feed.
Back up the database first:
cd ~/.smartdecision
sudo docker compose stop app
cp local.db local.db.backup-$(date +%F)
sudo docker compose start app Then download the current installer and run it again:
curl -fsSL https://get.smartdecision.io/install.sh -o install.sh
sh install.sh --llm=builtin
The installer reuses the license key from your last run and installs the newest version your key covers. Pass
the same --llm options you installed with, or answer the question again. On start, the new version
updates the database by itself. Your data stays in local.db. To install a specific version, add
--version=1.4.0.
Environment variables
The installer writes these to ~/.smartdecision/.env, and Compose passes them to the app. After you
edit .env, run sudo docker compose up -d in that directory.
| Variable | What it does |
|---|---|
SMARTDECISION_LICENSE | The license key. When set, it overrides the key stored in the app, and admins can't change it in Settings. |
SMARTDECISION_DOWNLOAD_KEY | The key the installer downloads with. The app installs it on its first start, unless a key is already stored. After that, admins manage the key in Settings. |
SMARTDECISION_URL |
The address apps and teammates use, set by the installer (see --url). An address set
in Settings → Server address takes its place. Empty means the browser's address.
|
LLM_URL | Base URL of your own AI server. Empty means no AI. |
LLM_MODEL | Model name sent with each request. The built-in AI uses smartdecision. |
LLM_API_KEY | Bearer token for the endpoint. Leave empty if it needs none. |
LLM_WARMUP | true loads the model when someone opens New decision, so the first draft is
faster. The installer sets false for your own AI server, so it only loads a model
when someone drafts.
|
COMPOSE_PROFILES | ai runs the built-in AI container. Empty does not. |
The app also reads two variables that the generated compose.yaml does not pass. They apply only
when you run the SmartDecision image with your own Compose file or docker run:
| Variable | What it does |
|---|---|
PORT | The port the app listens on inside the container. Default 8080. |
JWT_SECRET | The key that signs sign-in sessions, at least 32 bytes. Without it, the app generates one on first start and keeps it in the database. Changing it signs everyone out. |