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-plugin package and run the installer again.
  • Internet access to get.smartdecision.io while 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:

Shell
curl -fsSL https://get.smartdecision.io/install.sh -o install.sh
sh install.sh

The installer:

  1. Asks for your license key. Paste it from your welcome email.
  2. Asks how SmartDecision should draft decisions: the built-in AI, your own AI server, or no AI. See AI: built-in or your own.
  3. Checks Docker, and installs it if it is missing.
  4. Downloads the newest SmartDecision version your key covers, checks its checksum and loads it into Docker.
  5. With the built-in AI, downloads the model (about 2.5 GB). If the download stops, run the installer again and it resumes.
  6. Writes its configuration to ~/.smartdecision and 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:

Shell
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 (container smartdecision): the web app and the Resolve API, published on port 8080.
  • llm (container smartdecision-llm): the built-in AI. It is in the ai Compose 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:

Shell
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:

Shell
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 calls LLM_URL/chat/completions to draft, and LLM_URL/models to check that the AI is available.
  • LLM_MODEL: the model name sent with each request.
  • LLM_API_KEY: sent as Authorization: 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

  1. Open http://<your-server>:8080 and sign up. The first account becomes the admin.
  2. The license key you gave the installer is already in place. An admin can replace it in Settings → License.
  3. 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:

Shell
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:

Shell
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:

Shell
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:

Shell
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.