Razona
Un modelo abierto (nemotron-3-nano:30b) vía Ollama Cloud planifica y decide. El sistema de tools es propio: definiciones declarativas con Zod, serializadas a JSON Schema. Nada de SDKs de agentes entre tu prompt y el modelo.
self-hosted · telegram · sandbox docker
Corre en tu máquina.
Corre en tu máquina.
Responde en tu bolsillo▌
Aki es un agente de IA autónomo: escucha por Telegram, razona con un modelo abierto vía Ollama Cloud y ejecuta comandos reales dentro de un sandbox Docker aislado. Sin SDKs de agentes — cada decisión es suya.
$ git clone https://github.com/beresiartejuan/aki-assistant-ai.git
3 serviciosgateway · core · sandbox
15 rondasde tools por segmento
4 capasde memoria
0 SDKsde agentes
aki · @aki_assistant_bot
● online
aki, generá un CSV con las fases de la luna de octubre
run_command
python3 moonphases.py
✓ 12 KB → lunas_octubre.csv
Listo — 4 fases, día por día. Te lo mando: lunas_octubre.csv 📎
Qué es aki
función
acción
continuidad
Un asistente que decide, ejecuta y aprende
Tres responsabilidades bien separadas, orquestadas sin frameworks: lo que razona no ejecuta, lo que ejecuta no recuerda, y lo que recuerda no sale de tu equipo.
Ejecuta
Cada run_command cae en un contenedor Docker endurecido: rootfs de solo lectura, sin capabilities, límite de 2 GB de RAM y usuario sin privilegios. Los archivos solo llegan a tu chat si Aki los marca con deliver_file.
Recuerda
Entre tareas consolida aprendizajes en memoria semántica: embeddings locales y vectores en LanceDB, dedupe por similitud coseno ≥ 0,90 y TTL de 30 días. Los hechos clave se versionan — nunca se pisan sin rastro.
El razonamiento viaja; tus datos no. La ejecución, los archivos, los episodios y la memoria viven en tu máquina — el LLM remoto solo lee el prompt y el contexto que tú le envías.
Instalación
De cero a tu bot en línea, en cinco pasos
Requisitos: Node.js ≥ 22.5 (usa node:sqlite nativo), pnpm ≥ 10, Docker, Ollama local para embeddings, y un bot creado con @BotFather.
Cloná e instalá dependencias
Monorepo con pnpm workspaces: gateway, agente, sandbox y paquete reservado.
$ git clone https://github.com/beresiartejuan/aki-assistant-ai.git $ cd aki-assistant-ai $ pnpm install
Creá los archivos de entorno
Cada paquete carga su propio .env. Las cuatro variables imprescindibles están en la tabla de abajo.
$ touch packages/agent-core/.env $ touch packages/executor/.env $ touch packages/telegram-gateway/.env
Construí la imagen del sandbox
Contenedor Ubuntu minimal desde donde Aki ejecuta comandos por tarea, sin tocar tu host.
$ docker build -f packages/executor/docker/sandbox.Dockerfile \ -t aki-sandbox:latest packages/executor/docker/
Bajá el modelo de embeddings local
La memoria semántica se vectoriza con Ollama local — ese cómputo nunca se delega a la nube. Requiere Ollama instalado y corriendo en 127.0.0.1:11434.
$ ollama pull qwen3-embedding:0.6b
Levantá los tres servicios
En tres terminales separadas, en este orden: sandbox → cerebro → gateway.
# terminal 1 — sandbox de ejecución $ pnpm --filter @aki/executor dev #:3100 # terminal 2 — cerebro del agente $ pnpm --filter @aki/agent-core dev #:3000 # terminal 3 — gateway de Telegram $ pnpm --filter @aki/telegram-gateway dev #:3200 ✓ Escribile al bot por Telegram — Aki responde desde tu máquina.
Variables de entorno
Cuatro valores y arranca
Los tres .env del paso 02 usan las mismas variables en cada paquete. Hay muchas más (timeouts, límites, modelo), pero estas cuatro son obligatorias.
| Variable | Archivo | Cómo obtenerla |
|---|---|---|
| §OLLAMA_API_KEY | agent-core/.env | API key de Ollama Cloud — ollama.com/settings/keys |
| §TELEGRAM_BOT_TOKEN | telegram-gateway/.env | Token que te da @BotFather al crear el bot |
| §ALLOWED_TELEGRAM_USER_IDS | telegram-gateway/.env | Tu ID numérico de Telegram — consultalo con @userinfobot |
| §INTERNAL_API_KEY | los tres /.env | Shared secret de auth inter-servicios — generalo una sola vez (ver al lado) |
Internal API key
Los tres servicios se autentican entre sí con este valor (header x-internal-key). Generá uno fuerte:
$ openssl rand -hex 32 # pega el mismo valor en los tres .env
⚠︎ Sin allowlist, cualquiera habla con tu bot
Si no definís ALLOWED_TELEGRAM_USER_IDS, el bot procesa mensajes de cualquier usuario de Telegram. En producción, configurá siempre tu ID.
Arquitectura
Las partes de Aki y cómo trabajan entre sí
Monorepo con pnpm workspaces. Cada pieza es un servicio HTTP propio en 127.0.0.1, autenticado por x-internal-key. Lo que conecta a cada una con la siguiente es lo importante:
↓tu mensaje · HTTPS long polling
P1
telegram-gateway
Bot grammY con cola persistente y checkpoint de update_id. Allowlist de usuarios y entrega de resultados + archivos al chat.
puerto :3200
↓encola el mensaje → cerebro
P2
agent-core
Loop agéntico con continuación automática (hasta 3 segmentos × 15 rondas de tools). Sistema de tools propio, memoria en capas y consolidación de aprendizajes.
puerto :3000
↓invoca tools → run_command · deliver_file …
P3
executor
Sandbox Docker endurecido: un workspace por tarea, artifacts vía HTTP, límites de RAM/PIDs/tiempo. El host queda intacto.
puerto :3100
↑resultado + artifacts → gateway → tu chat
P4
event-manager
Reservado para contratos compartidos entre gateway y agente. Hoy: vacío a propósito.
reservado
Ollama Cloud · razonamiento (remoto)
Ollama local · embeddings :11434
SQLite + LanceDB · memoria
Docker · sandbox aislado
Memoria en 4+1 capas
Lo que Aki aprende hoy lo aplica mañana
CAPA 0
Constitución
Reglas inmutables inyectadas al system prompt. Solo lectura para el agente.
CAPA 1
Scratchpad
Notas efímeras por tarea, se reinyectan al continuar a otro segmento.
CAPA 2
Episodios
Historial append-only en SQLite: acciones y observaciones de cada tarea.
CAPA 3
Aprendizajes
Instrucciones generales vectorizadas en LanceDB. Dedupe coseno ≥ 0,90, TTL 30 días.
CAPA 4
Hechos
Preferencias y datos clave, versionados: nunca se pisa un valor sin rastro.