1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
# Coinos
A bitcoin web wallet with built-in support for Lightning, Liquid, Nostr, and Ark. Run it as a personal wallet on top of your own node, or deploy a public instance like [coinos.io](https://coinos.io).
This repo is the API server. The frontend is at [coinos/coinos-ui](https://github.com/coinos/coinos-ui).
## Getting Started
```bash
bash <(curl -s https://raw.githubusercontent.com/coinos/coinos-server/staging/setup.sh)
```
Or clone and run manually:
```bash
git clone https://github.com/coinos/coinos-server.git
cd coinos-server
./setup.sh
```
That's it. The script installs Docker if needed, downloads a pre-built regtest snapshot with funded wallets and Lightning channels, pulls ~500MB of container images, and starts everything. Takes a few minutes on first run.
```
API server http://localhost:3119
Block explorer http://localhost:3000
Nostr relay ws://localhost:7777
```
Start the frontend in a separate terminal:
```bash
cd ~/coinos-ui && bun dev
```
### Requirements
- Linux or macOS (Docker auto-installed on Linux; install [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/) on macOS)
- ~2GB disk space
## How It Works
The server runs as a set of Docker containers orchestrated by `compose.yml`:
| Container | Image | What it does |
|-----------|-------|-------------|
| **app** | coinos-base | API server (Hono/Bun), bind-mounted from this repo |
| **bc** | bitcoin:30.2 | Bitcoin Core (regtest) |
| **lq** | elements:23.3.2 | Liquid sidechain |
| **cl, clb, clc** | lightningd:v25.12.1 | Core Lightning nodes (3 for testing) |
| **db** | valkey:8.0-alpine | User data (Redis-compatible) |
| **tb** | tigerbeetle | Double-entry accounting ledger |
| **sf** | strsrv | Nostr relay (strfry) |
| **cs** | chopsticks | Block explorer API |
| **eb** | electrs | Electrum server |
| **arc** | kvrocks | Archive cache (RocksDB-backed) |
All `ghcr.io/coinos/*` images share a common base layer (~196MB downloaded once).
### Optional Services
Uncomment in `compose.yml` to enable:
- **Ark** (arkd, arkd-wallet, nbxplorer) — off-chain UTXO protocol
- **Cashu** (nutshell) — ecash mint backed by Lightning
## Development
```bash
# Mine a block
docker exec bc bitcoin-cli -regtest generatetoaddress 1 \
$(docker exec bc bitcoin-cli -regtest getnewaddress)
# Lightning CLI
docker exec cl lightning-cli --network=regtest getinfo
docker exec cl lightning-cli --network=regtest listpeerchannels
# Logs
docker compose logs -f app
# Restart a service
docker compose restart app
# Stop / start
docker compose down
docker compose up -d
```
### Project Structure
```
config.ts App configuration (from config.ts.sample)
compose.yml Docker services (from compose.yml.sample)
data/ Runtime data for all services (gitignored)
lib/ Core libraries (payments, lightning, ark, etc.)
routes/ HTTP route handlers
setup.sh One-command dev environment setup
sampledata/ Default configs copied to data/ on first run
```
### Reset
```bash
rm -rf data config.ts compose.yml
./setup.sh
```
### Rebuild from Scratch
To skip the snapshot and generate wallets/blocks/channels manually:
```bash
./setup.sh --no-snapshot
```
## Contributing
1. Fork and clone
2. Run `./setup.sh`
3. Make changes — the app container bind-mounts this directory, so edits are live
4. `bun test` to run tests
5. Open a PR
## License
MIT
|
