Run an AI agent on your own machine: a hands-on look at VIKI

Curious about AI agents without the hosted lock-in? VIKI runs locally and focuses on capability gating, sandboxed access, and security.

Feb 20, 2026

VIKI sits in the growing space between “chat with a model” and “hand over the keys to a hosted agent.” If you like the idea of an agent that can plan, read files, and run tools, but you do not like sending your workflow to somebody else’s servers, this project is worth watching.

The promise here is simple. Your model runs where you run it. Your data stays where you store it. Tool use stays behind a permission wall you can actually see.

The headline: a local-first agent that ships fast

VIKI shipped its first public pre-release, v7.3.1, dated February 17, 2026. The release adds Docker support, file upload in the chat UI, and a more familiar, ChatGPT-style dashboard layout.

That matters because it moves the project from “interesting repo” to “something you can try without wrestling it for a weekend.”

Why local-first matters for agents

“Agent” usually implies three things: persistence, tool use, and autonomy.

Persistence means the system remembers what happened yesterday. Tool use means it can do more than talk, like reading files or running commands. Autonomy means it can chain steps without you copy-pasting between windows.

Those are also the three places hosted products tend to pull you into their stack. Memory becomes their database. Tools become their runtime. Autonomy becomes their policy layer.

A local-first agent flips that. You keep the runtime on your machine, and you decide what the agent can do. If the internet goes out, the agent does not vanish. If a provider rate-limits, your local workflow still works. If you are handling sensitive files, you get to choose whether they ever leave your disk.

What VIKI actually is

Think of VIKI as an orchestration and control layer that runs on your machine. The main repository describes it as a sovereign agent system built to coordinate models and skills, persist state locally, and keep tool use bounded by explicit gating.

In the current structure, VIKI ships as a few moving parts:

A CLI entry point for local interaction
A Flask API server that your UI talks to
A React dashboard, including a voice-oriented “hologram face” view
An optional Docker setup for the API server, documented in the project’s DOCKER.md guide

If you already run local models with Ollama, VIKI aims to sit on top and handle coordination, state, and tool gating. In other words, you bring the model. VIKI brings the workflow scaffolding.

Autonomy, with a permission layer you can audit

Local agents only feel “yours” when three pieces stay in your control: which model you run, where your data lives, and what tools are allowed to execute.

VIKI makes that intent visible in its environment template. The project’s .env.example includes optional placeholders for cloud keys, plus toggles that hint at stricter modes like air-gapped operation and simulate-only workflows.

That might sound like a detail. It is the difference between a project that tolerates local use and a project that defaults to it.

If you want to pressure-test the “control” claim, look for three signals when you try VIKI:

Can you run it without configuring third-party keys
Can you see where state is stored on disk
Can you observe when a tool is about to run, and stop it

VIKI’s docs are written like the maintainers expect you to care about those questions.

Security posture that reads like engineering, not marketing

Agents that can touch your filesystem and shell are powerful. They also become dangerous quickly if the guardrails are vague.

VIKI’s security setup documentation is unusually concrete for an early project. The SECURITY_SETUP.md doc describes required API authentication (an API key that both server and UI must share), a separate admin secret for privileged actions, path sandboxing with explicit blocks for sensitive system locations, and a validation step before skills execute.

A few specifics are worth calling out because they map to real-world failure modes:

File access stays inside allowed roots like workspace and data directories, with explicit blocks for system paths
Shell command chaining characters like ;, &&, ||, and | are treated as higher-risk, and can trigger confirmation to prevent “safe command plus hidden destructive command”
SSRF protections are built into web research, blocking private IP ranges, loopbacks, and cloud metadata endpoints like 169.254.169.254

This is the right direction. It acknowledges the threat model you actually get with agents, including prompt injection and accidental escalation.

Quick walkthrough: CLI-only local setup

If you want the simplest path, start with the CLI. The project includes a more complete checklist in SETUP.md.

Install and start Ollama, then run:

ollama serve

Pull a starter model:

ollama pull phi3

Clone and install VIKI:

git clone https://github.com/Orythix/viki.git
cd viki
python -m venv .venv
# macOS/Linux:
source .venv/bin/activate
# Windows PowerShell:
# .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Create your .env and generate secrets:

cp .env.example .env  # Windows: copy .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(32))"

Run the CLI:

python viki/main.py

Once it boots, a safe first check is /status, followed by /skills so you can see what is enabled before you let it touch files or run commands.

If you are evaluating it for real work, run a few “boring” tasks first. Summarize a directory listing. Parse a local markdown file. Ask it to plan a multi-step task, then watch how it asks for permission before it tries anything risky.

Boring is good. Boring means predictable.

Quick walkthrough: dashboard UI for chat and system panels

If you prefer a browser UI, VIKI typically runs as two local processes: the API server plus the React dashboard.

Start the API server:

python viki/api/server.py

Then configure the UI to send the same API key. The UI notes live in the project’s ui/README.md.

Run the UI:

cd ui
npm install
npm run dev

Open http://localhost:5173 in your browser.

A good first UI test is to send a message and confirm you get a response. After that, try attaching a small text file through the upload control added in v7.3.1, and ask for a short summary.

One practical tip: keep the agent’s workspace folder separate from anything sensitive while you learn its behavior. That gives you room to experiment without worrying about accidental reads or writes.

Quick walkthrough: Docker for the API server

VIKI’s pre-release v7.3.1 also introduces Docker support for the API server. The project’s Docker guide covers the setup details, including how to point the container at your Ollama host.

Build and run:

docker compose up --build

One caution from the docs is worth repeating. Running Docker commands through an agent, especially with the Docker socket mounted, turns into a machine-level capability. Treat it like root access. Enable it only when you need it, and only on a machine you are prepared to recover.

Hardware expectations for local VIKI use

Your real requirements depend on which model you run and how aggressively you use tools. VIKI’s own performance notes mention that embedding models and voice VAD run on CPU by default, which can keep GPU pressure down.

Here is a practical way to think about the tiers, using Amazon search links you can swap for your preferred retailers:

Minimum, CPU-first: Ryzen 7 7700, 32GB DDR5 RAM, 1TB NVMe SSD
Recommended for daily local inference: RTX 4060, 64GB DDR5 RAM, 2TB NVMe SSD
Heavy use for larger models and parallel tool work: RTX 4070 or RTX 4090, 128GB DDR5 RAM, 4TB NVMe SSD

If you want embeddings or VAD to run on GPU, the performance notes and environment template list toggles you can enable, so you can decide whether the tradeoff is worth it.

Share Popular AI

Licensing, plus one detail to verify

The repository includes an MIT license in its LICENSE file.

The draft also notes a mismatch where a README badge appears to reference Apache 2.0. In cases like that, rely on the LICENSE file as the source of truth until the maintainer reconciles the docs.

Practical gotchas before you bet your workflow on it

VIKI looks promising, but it is still early, and early projects have seams.

Keep outbound calls intentional. If you want offline to mean offline, leave third-party API keys unset and keep research tooling disabled.
Treat local logs as sensitive. Local audit trails are useful, and they also create a data footprint on your machine.
Reproducibility matters. The setup docs and README may drift, so pin versions and keep notes as you go.

If you evaluate VIKI like you would evaluate any tool that can execute actions, you will get better outcomes. Start with read-only tasks. Move to write tasks inside a scratch directory. Only then try shell execution. Work your way up the capability ladder.

Bottom line

VIKI is interesting because it treats local control as the starting point. If you have been waiting for an agent you can run on your own hardware, with your own models, and with fewer black-box layers, start by reading the repo and the security setup doc, then test it in a locked-down mode before you expand permissions.

Explore more from Popular AI:

Start here | Local AI | Fixes & guides | Builds & gear | AI briefing

Comments

Ready for more?