# Environment

This document describes the current development environment configuration, including services, ports, environment variables, and setup steps.

## Host Information

**Primary Host**: `aitbc1`
- OS: Linux (6.11.10-amd64)
- Workspace: `/root/.openclaw/workspace`
- Python: 3.10+ (node v22.22.1 also installed for tooling)
- Shell: zsh
- Timezone: UTC

**Sibling Host**: `aitbc`
- Remote machine (details may differ)
- Communication: via Gitea API, SSH, P2P

## Repository Layout

```
/root/.openclaw/workspace/
├── ai-memory/          # Structured memory (canonical)
│   ├── daily/
│   ├── architecture/
│   ├── decisions/
│   ├── failures/
│   ├── knowledge/
│   └── agents/
├── memory/             # Legacy per-agent hourly logs (deprecated)
│   ├── aitbc/
│   ├── aitbc1/
│   └── archive/
├── MEMORY.md           # Curated long-term notes (to be migrated)
├── packages/py/        # Python packages (aitbc-*)
├── apps/
│   ├── coordinator-api/
│   └── blockchain-node/
├── cli/
│   └── aitbc_cli/
├── scripts/
├── AGENTS.md
├── SOUL.md
└── README.md
```

## Services & Ports

| Service            | Path                         | Port | Protocol | Status (typically) |
|--------------------|------------------------------|------|----------|--------------------|
| Coordinator API    | `apps/coordinator-api`       | 8000 | HTTP     | Running            |
| Blockchain RPC     | `apps/blockchain-node`       | 8006 | HTTP     | Running            |
| Blockchain P2P     | `apps/blockchain-node`       | 8005 | WebSocket| Running            |
| Wallet Daemon      | `apps/blockchain-node`       | 8015 | HTTP     | Running            |
| AI Provider        | Launched via CLI `ai serve`  | 8008 | HTTP     | On-demand          |
| Redis              | System service               | 6379 | TCP      | Running (dev)      |

## Environment Variables

Common variables used:

- `LOG_LEVEL`: Logging level (default `INFO`). Set to `DEBUG` for verbose.
- `DATABASE_URL`: Database connection string. Example: `sqlite+aiosqlite:///data/coordinator.db`
- `REDIS_URL`: Redis connection. Default: `redis://localhost`
- `HOST`: Service host (usually `0.0.0.0` to bind all)
- `PORT`: Service port (overrides default)
- `GITEA_TOKEN`: API token for Gitea (automation scripts). Not in repo.

Services typically read these from environment or use defaults.

## Virtual Environments

Each package/service may have its own virtualenv under `venv/` or use a central one.

- CLI venv: `/opt/aitbc/cli/cli_venv` (or `/opt/aitbc/cli/venv`)
- Coordinator venv: (maybe) `apps/coordinator-api/venv`
- Blockchain node venv: `apps/blockchain-node/venv` or system Python

**Important**: Activate the correct venv before running commands:
```bash
source /opt/aitbc/cli/cli_venv/bin/activate
aitbc --help
```

## Setup Steps (New Developer)

1. Clone repository to workspace.
2. Install **Poetry** (if not installed).
3. Install dependencies for each package:
   ```bash
   cd packages/py/aitbc-core && poetry install
   cd ../aitbc-crypto && poetry install
   cd ../aitbc-sdk && poetry install
   cd ../aitbc-agent-sdk && poetry install
   ```
4. Install CLI dependencies (either via Poetry in `cli/` or use venv):
   ```bash
   cd cli
   python -m venv venv
   source venv/bin/activate
   pip install -e .
   ```
5. Install service dependencies for `coordinator-api` and `blockchain-node` similarly.
6. Start Redis: `sudo systemctl start redis` or `redis-server`.
7. Initialize and start coordinator DB:
   ```bash
   cd apps/coordinator-api
   source venv/bin/activate
   python -m app.init_db
   uvicorn app.main:app --reload --port 8000
   ```
8. Start blockchain devnet:
   ```bash
   cd apps/blockchain-node
   source venv/bin/activate
   ./scripts/devnet_up.sh
   ```
9. Verify services:
   ```bash
   curl http://localhost:8000/health
   curl http://localhost:8006/health
   ```
10. Configure Gitea token for automation: `export GITEA_TOKEN=...` in shell profile or cron environment.

## Testing

- Run package tests with `pytest` inside the package directory or via `poetry run pytest`.
- CLI tests: `aitbc <command>` after activating CLI venv.
- Integration tests may require all services running.

## Known Issues

- Starlette must be pinned `<0.38`.
- Docker Compose command name varies (`docker compose` vs `docker-compose`).
- Absolute paths in some old scripts; replaced with relative.
- Redis is dev-only; not hardened for internet.

## Monitoring

- Health endpoints:
  - Coordinator: `GET /health` → `{"status":"ok"}`
  - Blockchain: `GET /health` or `/status`
  - Wallet: `GET /wallet/balance?addr=...`
- Logs: Check stdout/stderr of services, or systemd journal if installed as services.

## Troubleshooting

- Port in use: `lsof -i:<port>` to find culprit.
- Database locked: ensure only one process writes; use `IF NOT EXISTS` for idempotent init.
- Import errors: verify `PYTHONPATH` and virtualenv activation.
- Redis connection refused: start Redis server (`systemctl start redis`).

## Future Improvements

- Production P2P without Redis.
- TLS for all services.
- Centralized configuration management (e.g., TOML file).
- Docker Compose for whole stack (robustified).

---

*Update this file whenever environment configuration changes.*