feat(bootstrap): add initial one-time password onboarding flow

Author: pRizz

README.md

@@ -154,6 +154,15 @@ occ install
 occ start
 ```
 
+If this is the first startup with no configured users, the container logs will print an **Initial One-Time Password (IOTP)**.
+Open the login page, use the first-time setup panel, and create your first account. The IOTP is invalidated after successful signup.
+
+Quick IOTP extraction from logs:
+
+```bash
+occ logs | grep -F "INITIAL ONE-TIME PASSWORD (IOTP): " | tail -n1 | sed 's/.*INITIAL ONE-TIME PASSWORD (IOTP): //'
+```
+
 ### From source (install locally)
 
 ```bash
@@ -338,7 +347,17 @@ occ config show
 
 ## Authentication
 
-opencode-cloud uses **PAM (Pluggable Authentication Modules)** for authentication. Users created via `occ user add` authenticate to the opencode web UI.
+opencode-cloud uses **PAM (Pluggable Authentication Modules)** for authentication.
+
+First boot path:
+- If no users are configured, startup logs print an Initial One-Time Password (IOTP).
+- Extract only the IOTP quickly: `occ logs | grep -F "INITIAL ONE-TIME PASSWORD (IOTP): " | tail -n1 | sed 's/.*INITIAL ONE-TIME PASSWORD (IOTP): //'`
+- Enter that IOTP in the web login page first-time setup panel.
+- Complete signup (username + password) to create the first Linux user account in the container.
+- The IOTP is deleted after the first successful signup.
+
+Admin path:
+- You can always create/manage users directly via `occ user add`, `occ user passwd`, and related user commands.
 
 ### Creating Users
 
@@ -365,14 +384,6 @@ User accounts (including password hashes and lock status) persist across contain
 The CLI stores user records in a managed Docker volume mounted at `/var/lib/opencode-users` inside the container.
 No plaintext passwords are stored on the host.
 
-### Legacy Authentication Fields
-
-The `auth_username` and `auth_password` config fields are **deprecated** and ignored. They are kept in the config schema for backward compatibility with existing deployments, but new users should be created via `occ user add` instead.
-
-To migrate from legacy fields:
-1. Create a PAM user: `occ user add <username>`
-2. The legacy fields will be automatically cleared on next config save
-
 ### Rebuilding the Docker Image
 
 When developing locally or after updating opencode-cloud, you may need to rebuild the Docker image to pick up changes in the embedded Dockerfile:

docs/deploy/digitalocean-droplet.md

@@ -70,18 +70,31 @@ Pull and start the sandbox image:
 occ start --pull-sandbox-image
 ```
 
-### 6) Create the first PAM user
+### 6) Complete first-time signup with Initial One-Time Password (IOTP)
 
-Recommended: generate a strong password:
+After `occ start`, check logs for the IOTP:
 
 ```bash
-occ user add admin --generate
+occ logs
+```
+
+Extract just the IOTP value (optional):
+
+```bash
+occ logs | grep -F "INITIAL ONE-TIME PASSWORD (IOTP): " | tail -n1 | sed 's/.*INITIAL ONE-TIME PASSWORD (IOTP): //'
 ```
 
-Scripting mode:
+Open the web login page through your SSH tunnel and use the first-time setup panel:
+- Enter the IOTP from logs
+- Choose username + password
+- Submit signup (this creates the first Linux user inside the container)
+
+The IOTP is invalidated after successful signup.
+
+Admin fallback:
 
 ```bash
-occ user add admin --generate --print-password-only
+occ user add admin --generate
 ```
 
 ### 7) Access via SSH tunnel (recommended default)
@@ -96,7 +109,7 @@ Then open:
 
 - `http://localhost:3000`
 
-Log in with the user you created.
+Log in with the account you created in the first-time setup panel.
 
 ### 8) Enable reboot persistence via systemd (system-level)
 
@@ -240,8 +253,6 @@ docker run -d --name opencode-cloud-sandbox \
   -v opencode-workspace:/home/opencode/workspace \
   -v opencode-config:/home/opencode/.config/opencode \
   -v opencode-users:/var/lib/opencode-users \
-  -e OPENCODE_BOOTSTRAP_USER=admin \
-  -e OPENCODE_BOOTSTRAP_PASSWORD='change-me' \
   prizz/opencode-cloud-sandbox:15.2.0
 ```
 
@@ -260,6 +271,20 @@ ssh -L 3000:localhost:3000 root@<droplet-ip>
 
 Then open `http://localhost:3000`.
 
+Before signing in, read the container logs and copy the Initial One-Time Password (IOTP):
+
+```bash
+docker logs opencode-cloud-sandbox
+```
+
+Extract only the IOTP value:
+
+```bash
+docker logs opencode-cloud-sandbox 2>&1 | grep -F "INITIAL ONE-TIME PASSWORD (IOTP): " | tail -n1 | sed 's/.*INITIAL ONE-TIME PASSWORD (IOTP): //'
+```
+
+Use the login page first-time setup panel with that IOTP, then create your username/password.
+
 ### 5) Expose publicly (optional)
 
 - Change to `-p 0.0.0.0:3000:3000` (or `-p 3000:3000`)
@@ -286,4 +311,3 @@ systemd logs (if installed via `occ install`):
 ```bash
 journalctl -u opencode-cloud -f
 ```
-

packages/cli-rust/src/commands/start.rs

@@ -574,6 +574,28 @@ fn display_network_exposure_warning(bind_addr: &str) {
     eprintln!();
 }
 
+fn display_bootstrap_mode_warning(bind_addr: &str) {
+    eprintln!();
+    eprintln!(
+        "{} {}",
+        style("Bootstrap mode enabled:").yellow().bold(),
+        style("no preconfigured users were found.").yellow()
+    );
+    eprintln!();
+    eprintln!(
+        "The service will start on {} and print an Initial One-Time Password (IOTP) in container logs.",
+        style(bind_addr).cyan()
+    );
+    eprintln!("Open the login page and use the first-time setup panel with that IOTP.");
+    eprintln!("The IOTP is invalidated immediately after the first successful signup.");
+    eprintln!();
+    eprintln!(
+        "Admin alternative: {}",
+        style("occ user add <username>").dim()
+    );
+    eprintln!();
+}
+
 /// Start the opencode service
 ///
 /// This command:
@@ -683,20 +705,13 @@ pub async fn cmd_start(
         VersionMismatchAction::Continue => {}
     }
 
-    // Security check: block first start without security configured
+    // Determine whether this is first container start
     let is_first_start = !container_exists(&client, CONTAINER_NAME).await?;
 
-    if is_first_start && config.users.is_empty() && !config.allow_unauthenticated_network {
-        return Err(anyhow!(
-            "{}\n\n\
-             No users are configured for authentication.\n\
-             The service cannot start without security configured.\n\n\
-             Quick setup:\n  {}\n\n\
-             Or allow unauthenticated access (not recommended):\n  {}",
-            style("Security not configured").red().bold(),
-            style("occ setup").cyan(),
-            style("occ config set allow_unauthenticated_network true").dim()
-        ));
+    let bootstrap_mode =
+        is_first_start && config.users.is_empty() && !config.allow_unauthenticated_network;
+    if bootstrap_mode && !quiet {
+        display_bootstrap_mode_warning(bind_addr);
     }
 
     // Check for port mismatch on existing container

packages/core/README.md

@@ -154,6 +154,15 @@ occ install
 occ start
 ```
 
+If this is the first startup with no configured users, the container logs will print an **Initial One-Time Password (IOTP)**.
+Open the login page, use the first-time setup panel, and create your first account. The IOTP is invalidated after successful signup.
+
+Quick IOTP extraction from logs:
+
+```bash
+occ logs | grep -F "INITIAL ONE-TIME PASSWORD (IOTP): " | tail -n1 | sed 's/.*INITIAL ONE-TIME PASSWORD (IOTP): //'
+```
+
 ### From source (install locally)
 
 ```bash
@@ -338,7 +347,17 @@ occ config show
 
 ## Authentication
 
-opencode-cloud uses **PAM (Pluggable Authentication Modules)** for authentication. Users created via `occ user add` authenticate to the opencode web UI.
+opencode-cloud uses **PAM (Pluggable Authentication Modules)** for authentication.
+
+First boot path:
+- If no users are configured, startup logs print an Initial One-Time Password (IOTP).
+- Extract only the IOTP quickly: `occ logs | grep -F "INITIAL ONE-TIME PASSWORD (IOTP): " | tail -n1 | sed 's/.*INITIAL ONE-TIME PASSWORD (IOTP): //'`
+- Enter that IOTP in the web login page first-time setup panel.
+- Complete signup (username + password) to create the first Linux user account in the container.
+- The IOTP is deleted after the first successful signup.
+
+Admin path:
+- You can always create/manage users directly via `occ user add`, `occ user passwd`, and related user commands.
 
 ### Creating Users
 
@@ -365,14 +384,6 @@ User accounts (including password hashes and lock status) persist across contain
 The CLI stores user records in a managed Docker volume mounted at `/var/lib/opencode-users` inside the container.
 No plaintext passwords are stored on the host.
 
-### Legacy Authentication Fields
-
-The `auth_username` and `auth_password` config fields are **deprecated** and ignored. They are kept in the config schema for backward compatibility with existing deployments, but new users should be created via `occ user add` instead.
-
-To migrate from legacy fields:
-1. Create a PAM user: `occ user add <username>`
-2. The legacy fields will be automatically cleared on next config save
-
 ### Rebuilding the Docker Image
 
 When developing locally or after updating opencode-cloud, you may need to rebuild the Docker image to pick up changes in the embedded Dockerfile:

packages/core/src/docker/Dockerfile

@@ -581,6 +581,10 @@ RUN ls -la /home/opencode/.config/opencode/opencode.jsonc && cat /home/opencode/
 COPY packages/core/src/docker/files/entrypoint.sh /usr/local/bin/entrypoint.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh
 
+# Bootstrap helper for first-user onboarding (invoked by entrypoint and auth route via sudo)
+COPY packages/core/src/docker/files/opencode-cloud-bootstrap.sh /usr/local/bin/opencode-cloud-bootstrap
+RUN chmod 700 /usr/local/bin/opencode-cloud-bootstrap
+
 # Note: Don't set USER here - entrypoint needs root to use runuser
 # The tini mode drops privileges to opencode user via runuser