mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-07-09 16:00:52 +00:00
docs: add auth requirement and self-signed cert warning to quick-start (#481)
## Summary Fixes #468 and #470. The quick-start examples crashed on first run without a password, and the browser self-signed certificate warning was not documented anywhere a new user would see it. ## Changes - Add `--password` to all npx quick-start examples (main README + server README) - Document the three ways to configure auth: `--password`, env var, `auth.json` - Show `auth.json` schema so users understand the expected format - Add browser warning note to self-signed certificates section with step-by-step instructions for Chrome/Brave and Firefox - Mention `--https=false --http=true` as an alternative for local-only use ## Validation - Reviewed rendered markdown structure - Verified auth.json schema matches AuthFile interface in auth-store.ts
This commit is contained in:
Dark
GitHub
parent
01d9e46b3d
commit
cb3d4841e1
2 changed files with 56 additions and 6 deletions
|
|
@ -47,9 +47,13 @@ Download the latest installer for your platform from [Releases](https://github.c
|
|||
Run as a local server and access via browser. Perfect for remote development.
|
||||
|
||||
```bash
|
||||
npx @neuralnomads/codenomad --launch
|
||||
npx @neuralnomads/codenomad --password <your-password> --launch
|
||||
```
|
||||
|
||||
> **Authentication required:** The server requires a password on first run. You can pass it via `--password`, the `CODENOMAD_SERVER_PASSWORD` environment variable, or create an `auth.json` file (see [Server Documentation](packages/server/README.md)).
|
||||
|
||||
> **Self-signed certificate:** On first launch with HTTPS enabled (the default), your browser will show a "Your connection is not private" warning. This is expected — the server generates a local self-signed certificate automatically. Click **Advanced → Proceed to localhost** to continue. For local-only use without the warning, run with `--https=false --http=true`.
|
||||
|
||||
See [Server Documentation](packages/server/README.md) for flags, TLS, auth, and remote access.
|
||||
|
||||
### 🧪 Dev Releases
|
||||
|
|
@ -57,7 +61,7 @@ See [Server Documentation](packages/server/README.md) for flags, TLS, auth, and
|
|||
Bleeding-edge builds from the `dev` branch:
|
||||
|
||||
```bash
|
||||
npx @neuralnomads/codenomad-dev --launch
|
||||
npx @neuralnomads/codenomad-dev --password <your-password> --launch
|
||||
```
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -32,9 +32,11 @@
|
|||
You can run CodeNomad directly without installing it:
|
||||
|
||||
```sh
|
||||
npx @neuralnomads/codenomad --launch
|
||||
npx @neuralnomads/codenomad --password <your-password> --launch
|
||||
```
|
||||
|
||||
> **Authentication required:** The server requires a password. Pass it via `--password`, the `CODENOMAD_SERVER_PASSWORD` environment variable, or create an `auth.json` file (see [Authentication](#authentication) below).
|
||||
|
||||
To list all CLI options:
|
||||
|
||||
```sh
|
||||
|
|
@ -52,7 +54,7 @@ Or install it globally to use the `codenomad` command:
|
|||
|
||||
```sh
|
||||
npm install -g @neuralnomads/codenomad
|
||||
codenomad --launch
|
||||
codenomad --password <your-password> --launch
|
||||
```
|
||||
|
||||
### Install Locally (per-project)
|
||||
|
|
@ -61,7 +63,7 @@ If you prefer to install CodeNomad into a project and run the local binary:
|
|||
|
||||
```sh
|
||||
npm install @neuralnomads/codenomad
|
||||
npx codenomad --launch
|
||||
npx codenomad --password <your-password> --launch
|
||||
```
|
||||
|
||||
(`npx codenomad ...` will use `./node_modules/.bin/codenomad` when present.)
|
||||
|
|
@ -102,7 +104,7 @@ You can configure the server using flags or environment variables:
|
|||
If you want the latest bleeding-edge builds (published as GitHub pre-releases), use the dev package:
|
||||
|
||||
```sh
|
||||
npx @neuralnomads/codenomad-dev --launch
|
||||
npx @neuralnomads/codenomad-dev --password <your-password> --launch
|
||||
```
|
||||
|
||||
These environment variables control how CodeNomad checks for dev updates:
|
||||
|
|
@ -148,6 +150,14 @@ Certificates are valid for about 30 days and rotate automatically on startup whe
|
|||
codenomad --tlsSANs "localhost,127.0.0.1,my-hostname,192.168.1.10"
|
||||
```
|
||||
|
||||
> **Browser warning:** Self-signed certificates trigger a "Your connection is not private" warning in browsers on first visit. This is expected and safe for local development (127.0.0.1 / localhost):
|
||||
>
|
||||
> 1. **Chrome/Brave/Edge:** Click **Advanced** → **Proceed to 127.0.0.1 (unsafe)**
|
||||
> 2. **Firefox:** Click **Advanced** → **Accept the Risk and Continue**
|
||||
> 3. **Alternative:** For local-only development without the warning, run with `--https=false --http=true`
|
||||
>
|
||||
> **Note:** Only accept self-signed certificates for localhost/127.0.0.1 that you control. For remote hosts, use proper TLS certificates.
|
||||
|
||||
### Authentication
|
||||
|
||||
- Default behavior: CodeNomad requires a login (username/password) and stores a session cookie in the browser.
|
||||
|
|
@ -155,6 +165,42 @@ codenomad --tlsSANs "localhost,127.0.0.1,my-hostname,192.168.1.10"
|
|||
Use this only when access is already protected by another layer (SSO proxy, VPN, Coder workspace auth, etc.).
|
||||
If you bind to `0.0.0.0` while skipping auth, anyone who can reach the port can access the API.
|
||||
|
||||
#### Setting a password
|
||||
|
||||
**Practical setup options:**
|
||||
|
||||
1. **Runtime password (every start):** Use `--password <your-password>` or set `CODENOMAD_SERVER_PASSWORD=<your-password>` environment variable
|
||||
2. **Persistent password (UI setup):** Launch with `--generate-token`, complete the local bootstrap flow in your browser, then set a password through the UI settings
|
||||
|
||||
The `--password` flag and `CODENOMAD_SERVER_PASSWORD` env var are **runtime credentials** — they must be provided on every server start and are not persisted to disk.
|
||||
|
||||
**Advanced: `auth.json` internals**
|
||||
|
||||
The `auth.json` file (`~/.config/codenomad/auth.json`) is automatically created and managed by CodeNomad when you set a password through the UI. You generally don't need to edit this file manually. For reference, it uses the following scrypt-based schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"username": "codenomad",
|
||||
"password": {
|
||||
"algorithm": "scrypt",
|
||||
"saltBase64": "<base64-salt>",
|
||||
"hashBase64": "<base64-hash>",
|
||||
"keyLength": 64,
|
||||
"params": {
|
||||
"N": 16384,
|
||||
"r": 8,
|
||||
"p": 1,
|
||||
"maxmem": 33554432
|
||||
}
|
||||
},
|
||||
"userProvided": true,
|
||||
"updatedAt": "2026-05-18T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
Manual creation of this file is not recommended unless you have a helper to generate a valid scrypt `PasswordHashRecord`.
|
||||
|
||||
### Progressive Web App (PWA)
|
||||
|
||||
When running as a server CodeNomad can also be installed as a PWA from any supported browser, giving you a native app experience just like the Electron installation but executing on the remote server instead.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue