Skip to content

Optics

See where it connects.

Install the CLI on the machine where the program runs, then start that program under Vantio. You get the destination, the process, and the decision. A first connection is flagged when the destination is not on the allowlist.

Install with npm.

On Node, install the CLI, then start the program you already use.

npm i -g @vantio/cli
vantio run node agent.js

Install for Python.

Install the CLI with npm first. The vantio command comes from that package. Then install vantio-agent-sdk and start the program.

npm i -g @vantio/cli
pip install vantio-agent-sdk
vantio run python agent.py

Phantom Engine is designed to stop what is not allowed on the Linux systems you run. The lab proof is kernel enforcement for enrolled workloads on Ubuntu 24.04 in GCP and AWS, and a clean uninstall. Enterprise keeps who can change those rules with a person. Contact Vantio to deploy either one.

Contact VantioPhantom Engine

Troubleshooting

Start with the versions you have installed. Run vantio --version. For Python, run python -c 'import vantio; print(vantio.__version__)'. The published CLI this note matches is 0.3.24. The published Python package is 3.0.14. Python 3.1.0 is the unpublished source tree, not the package from PyPI.

No record file

  • If you ran node agent.js without vantio run, Optics was not attached.
  • If you ran vantio run python without vantio-agent-sdk on that interpreter, you get a warning and no calls are recorded. The program keeps running.
  • A Python run with no in-scope call writes nothing. An empty result is expected.
  • A Node run with no in-scope call still writes a file with an empty call list when the process exits normally.
  • If VANTIO_HOME is set, the record is written under that directory. vantio search, prove, tail, and discover read ~/.vantio/runs only. Look in the directory the writer used.
  • If the process was killed outright, or the machine lost power, the exit step did not run. There is no partial record.
  • A destination Optics does not record is ignored. Add it only when you intend to record it, with VANTIO_EXTRA_LLM_HOSTS.

vantio tail --follow stays quiet until the process exits. The file is written once at the end, not appended on each call.

A call you expected is missing

Confirm the client is one Optics records, confirm the destination name, and confirm this was the process you started with vantio run. The trace id is printed when that command starts. A browser, another language runtime, and a child process that drops the wrapper do not appear. That call was not recorded. It was not stopped.

A command exits with status 1

vantio search, vantio discover, and vantio prove --list exit 1 when a record file is unreadable or is not valid JSON. One bad file blocks those commands. vantio status keeps scanning and marks that run as an Optics error. Move the bad file aside, or fix the JSON, and try again. Optics does not rebuild an empty store for you.

The disk filled up

A failed write, including a full disk, is discarded. The program still exits, and no health record is stored. If a file you expected is missing after a full disk, the write was dropped. A failed vantio prove write exits 1 and prints the first line of the error.

The wrong run was selected

The file name is the trace id, with characters outside letters, numbers, underscore, and hyphen replaced, cut at 80 characters, plus .json. The same trace id overwrites that file. A short prefix can match more than one id. Pass a longer prefix. vantio prove reads the latest local record. vantio prove --list shows the records on this machine.

Python labels the provider as other

Published Python 3.0.14 stores the provider as other. Use the destination name. Node may show a shorter name for the same destination. Both can be correct for their writers.

An HTTP error looks like a network error

The CLI display uses the status code. An application outcome for status 400 through 599 is an application error. Published Python 3.0.14 can store an HTTP 500 from urllib as a network error. The requests, httpx, and aiohttp path in that same package can mark the call successful when a response comes back, including a 4xx or 5xx. The unpublished 3.1.0 tree stores those statuses as unsuccessful and does not call an HTTP status a network error. You only have that storage when you are running the unpublished tree.

A duration looks wrong

Durations use the wall clock. A clock step backward can store a negative duration on Node. Python clamps at zero. Timestamps are UTC. Order of timestamps is not a proof of cause. vantio demo always reports a duration of 0 ms.

Telemetry

The CLI ping stays off until VANTIO_TELEMETRY=1. The published Python shield() ping stays on until VANTIO_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1. vantio run python does not send that Python ping unless the program enters shield().

discover is not every process

vantio discover reads the records on this machine for a time window. The default is 24 hours. You can ask for 7 days or 30 days. A command you typed in a terminal, a browser, and any process you did not start with vantio run stay outside that list.

Login and keys

vantio login is not a help command in 0.3.24. Optics does not ask for a key. If an old ~/.vantio/config.json is still on disk, vantio logout deletes that file and does not delete your records. The command is omitted from vantio --help.

macOS or Windows with WSL

Optics runs on macOS, Linux, and Windows with WSL. Phantom Engine is designed to enforce rules on the Linux systems you run. The lab proof is kernel enforcement for enrolled workloads on Ubuntu 24.04 in GCP and AWS, and a clean uninstall.