# Headless Setup
Use the same CLI on a server or VPS. Keep secrets in files or environment
variables, not shell history.
## Wallet File
The preferred wallet file shape is:
```json
{
"address": "oct...",
"private_key_b64": "BASE64_PRIVATE_KEY",
"public_key_b64": "BASE64_PUBLIC_KEY"
}
```
`public_key_b64` is optional, but when supplied the CLI verifies that it matches
the private key.
Attach an existing plaintext wallet JSON:
```sh
octra-sqlite wallet attach /secure/path/wallet.json
```
For a new human-operated setup, `octra-sqlite setup` can guide you to the
official Octra wallet generator and copy the saved `wallet.json` into the local
octra-sqlite wallet path without rewriting the official file shape. Do not leave
the browser-downloaded copy in a synced Downloads folder after import.
Or import a private key without putting it in shell history:
```sh
printf '%s' "$OCTRA_PRIVATE_KEY_B64" | octra-sqlite wallet import --stdin --output /secure/path/wallet.json
```
The import command strips whitespace, derives the Octra address, writes a
normalized wallet JSON, and stores the file with restrictive permissions where
the OS supports it. Interactive setup uses a masked terminal prompt for private
key paste; headless setup should use `--stdin` or a pre-provisioned file.
Pre-provisioned files may use the official Octra wallet-generator shape
(`address` plus `keyPair.publicKey` / `keyPair.secretKey`) or octra-sqlite's
minimal normalized shape (`address`, `private_key_b64`, `public_key_b64`).
WebCLI `.oct` files are encrypted with a PIN; direct encrypted `.oct` import is
not enabled by default in this release.
Lock down the file before use:
```sh
chmod 600 /secure/path/wallet.json
octra-sqlite setup --yes --wallet /secure/path/wallet.json --network devnet
```
For service users, keep the wallet and config in an explicit service directory
with restrictive group access:
```sh
sudo install -d -m 0750 -o root -g octra-sqlite /etc/octra-sqlite
sudo install -m 0640 -o root -g octra-sqlite wallet.json /etc/octra-sqlite/wallet.json
```
## Config Path
By default, config lives at `~/.octra/sqlite.json`. Override it per process:
```sh
OCTRA_SQLITE_CONFIG=/secure/path/sqlite.json octra-sqlite status
```
Example service config:
```json
{
"network": "mainnet",
"wallet": "/etc/octra-sqlite/wallet.json",
"databases": {
"main": "oct://mainnet/oct..."
}
}
```
Lock it down the same way:
```sh
sudo install -m 0640 -o root -g octra-sqlite config.json /etc/octra-sqlite/config.json
OCTRA_SQLITE_CONFIG=/etc/octra-sqlite/config.json octra-sqlite wallet status main
```
## Server Checklist
Install with Rust/Cargo 1.88 or newer. `rustup stable` is recommended because
some Linux distributions ship older Cargo versions:
```sh
rustup toolchain install stable --profile minimal
cargo install --path . --locked
```
Pinned release install:
```sh
cargo install --git https://github.com/tomismeta/octra-sqlite --tag v0.5.2 --locked
```
If installing into a shared path, make the binary executable by the service
user or group:
```sh
sudo install -m 0755 ~/.cargo/bin/octra-sqlite /opt/octra-sqlite/bin/octra-sqlite
```
```sh
octra-sqlite config
octra-sqlite wallet status DATABASE
octra-sqlite database list
octra-sqlite database info DATABASE
octra-sqlite status DATABASE --ready
octra-sqlite verify DATABASE
```
For schema deploys:
```sh
octra-sqlite new DATABASE < schema.sql
```
If Circle creation succeeds but initializer SQL fails, the CLI prints the saved
database URI and recovery commands so the Circle can still be opened and
inspected. Initializer scripts can be partially applied, so inspect before
retrying.
For large imports and mirrors, avoid shell argument-sized SQL blobs:
```sh
octra-sqlite check DATABASE --sql-file dump.sql
octra-sqlite restore DATABASE --file dump.sql
```
Use `--json` or `--json-summary` for machine-readable output, and prefer full
`oct://NETWORK/<circle>` URIs in automation. For read proof/debugging, write
RPC traces to a file. Use `summary` when logs should stay compact:
```sh
octra-sqlite DATABASE --trace-rpc-json trace.jsonl "select 1;"
octra-sqlite DATABASE --trace-rpc-json trace.jsonl --trace-rpc-json-mode summary "select 1;"
```
Trace files can include SQL text, Circle IDs, wallet addresses, signatures, and
query responses. They do not include private keys, but store them like sensitive
logs: use restrictive permissions and do not commit them.
Normal command output and JSON do not print private keys or raw wallet JSON.
Opt-in RPC trace files can include request signatures because they are exact
debug/proof traces.