The AI that actually knows how you feel.
Sentient is an emotionally intelligent AI companion. The landing page collects waitlist signups at sentient.fyi. The API validates emails, assigns queue positions, and stores data with privacy-first hashing. Built for deployment on Akash Network's decentralized cloud with here.now handling the reverse proxy layer.
Browser
│
▼
sentient.fyi (Landing Page)
│
▼
here.now Reverse Proxy (/api/*)
│
▼
Akash Network (Docker Container)
│
▼
FastAPI + SQLite (Persistent Volume)
The landing page sits at sentient.fyi and posts signups to /api/waitlist. here.now proxies those API calls to the Akash-deployed container. The API validates emails (syntax + MX records), hashes IPs with SHA256 + salt, assigns sequential queue positions, and persists to SQLite.
Admin endpoints (list signups, export CSV, delete entries) require an API key via the X-API-Key header.
# Clone and run
git clone https://github.com/ToXMon/sentient.git
cd sentient
docker compose up --build
# API runs on http://localhost:8000
# Landing page on http://localhost:3000| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/waitlist |
None | Submit email to waitlist |
| GET | /api/waitlist/count |
None | Get total signup count |
| GET | /api/waitlist/position/{email_hash} |
None | Look up queue position by SHA256 hash |
| GET | /api/health |
None | Health check (status, version, uptime) |
| GET | /api/admin/waitlist |
API Key | List signups (paginated) |
| GET | /api/admin/waitlist/export |
API Key | Export all signups as CSV |
| DELETE | /api/admin/waitlist/{id} |
API Key | Delete a signup by ID |
| Variable | Required | Default | Description |
|---|---|---|---|
ADMIN_API_KEY |
Yes | — | API key for admin endpoints |
IP_HASH_SALT |
Yes | — | Salt for SHA256 IP hashing |
DB_DIR |
No | /data |
Directory for SQLite database |
ENABLE_DEV_CORS |
No | false |
Allow localhost CORS origins |
ENABLE_DOCS |
No | false |
Enable Swagger/ReDoc endpoints |
- Install the Akash CLI
- Set your secrets:
export ADMIN_API_KEY="your-secure-key" export IP_HASH_SALT="your-random-salt"
- Deploy:
akash deployment create api/deploy.yaml
- Update
api/.herenow/proxy.jsonwith the Akash endpoint URL
The SDL (api/deploy.yaml) requests 0.5 CPU, 512Mi RAM, 1Gi ephemeral + 2Gi persistent storage. The persistent volume survives container restarts.
# Build
docker build -t sentient-api ./api
# Run
docker run -d \
-p 8000:8000 \
-e ADMIN_API_KEY=your-key \
-e IP_HASH_SALT=your-salt \
-v sentient-data:/data \
sentient-apiapi/.herenow/proxy.json defines the routing rules:
POST /api/waitlist→ Akash endpointGET /api/health→ Akash endpointGET /api/waitlist/count→ Akash endpoint
Replace AKASH_ENDPOINT with the deployed container URL after Akash deployment.
sentient/
├── api/ # FastAPI backend
│ ├── app/
│ │ ├── main.py # App factory, middleware, CORS
│ │ ├── database.py # Async SQLAlchemy + SQLite
│ │ ├── models.py # WaitlistEntry model
│ │ ├── schemas.py # Pydantic v2 request/response schemas
│ │ ├── routers/
│ │ │ ├── waitlist.py # Public endpoints
│ │ │ └── admin.py # API-key-protected endpoints
│ │ └── utils/
│ │ ├── security.py # API key auth, IP hashing, XSS sanitization
│ │ └── validation.py # Email regex + MX record checks
│ ├── Dockerfile # Multi-stage Alpine build
│ ├── deploy.yaml # Akash Network SDL
│ └── requirements.txt
├── landing/ # Static landing page
│ └── index.html
├── docs/
│ ├── blueprint.md # Product system blueprint
│ └── architecture.md # Architecture deep-dive
├── .github/workflows/ci.yml # Build, lint, push to GHCR
├── docker-compose.yml # Local development
├── LICENSE
└── README.md
- Non-root container: Runs as
sentientuser, not root - CORS lockdown: Only
sentient.fyi,www.sentient.fyi, andhere.noworigins allowed in production - Rate limiting: 10 requests/minute per IP (public), 20-30/minute (admin)
- IP hashing: Client IPs stored as SHA256 + salt, never plaintext
- XSS prevention: All user input sanitized with HTML escaping and dangerous tag removal
- Security headers:
X-Content-Type-Options,X-Frame-Options, CSP, HSTS,Referrer-Policy,Permissions-Policy - Request size limit: 1MB max body size
- No stack trace leaks: Global exception handler returns generic 500 responses
- API key gating: Admin endpoints require
X-API-Keyheader - Docs disabled by default: Swagger/ReDoc only exposed when
ENABLE_DOCS=true
| Layer | Technology |
|---|---|
| API Framework | FastAPI 0.110+ |
| Database | SQLite via async SQLAlchemy 2.0 + aiosqlite |
| Validation | Pydantic v2 with email support |
| Rate Limiting | SlowAPI |
| DNS Verification | dnspython (MX record checks) |
| Runtime | Uvicorn with tini as PID 1 |
| Container | Python 3.11 Alpine, multi-stage build |
| CI/CD | GitHub Actions → GHCR |
| Deployment | Akash Network (decentralized) |
| Proxy | here.now reverse proxy |
| Landing Page | Static HTML/CSS/JS |
curl -X POST http://localhost:8000/api/waitlist \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "name": "Ada"}'Response (201):
{
"success": true,
"message": "You have been added to the waitlist!",
"queue_position": 42,
"is_duplicate": false
}# Hash the email first
EMAIL_HASH=$(echo -n "user@example.com" | sha256sum | cut -d' ' -f1)
curl http://localhost:8000/api/waitlist/position/$EMAIL_HASHResponse:
{
"found": true,
"email_hash": "a3c0b...",
"queue_position": 42,
"signup_date": "2025-04-15T12:00:00Z",
"message": "Position found"
}curl http://localhost:8000/api/waitlist/countResponse:
{
"total_signups": 150,
"message": "There are 150 people on the waitlist"
}curl http://localhost:8000/api/admin/waitlist?limit=10&offset=0 \
-H "X-API-Key: your-api-key"curl http://localhost:8000/api/admin/waitlist/export \
-H "X-API-Key: your-api-key" \
-o waitlist.csvcurl -X DELETE http://localhost:8000/api/admin/waitlist/42 \
-H "X-API-Key: your-api-key"curl http://localhost:8000/api/healthResponse:
{
"status": "healthy",
"version": "1.1.0",
"database": "connected",
"uptime_seconds": 3600.42
}