Osqueryi vs Osqueryd: Interactive Shell vs Daemon Mode

Osqueryi and osqueryd are not two tools. They are one engine with two jobs, and mixing up the jobs is the most common way osquery deployments underdeliver.

The shell, osqueryi, answers a person sitting at a keyboard. The daemon, osqueryd, runs a schedule forever and reports to your logging pipeline. Same tables, same SQL, same codebase, opposite operating models. Teams that treat the shell as the product never get fleet telemetry. Teams that jump straight to the daemon schedule queries they never tested and drown in output. This article draws the line precisely: what each mode does, what actually differs under the hood, and the handoff between them. For background on the agent itself, start with what osquery is.

What is osqueryi?

Osqueryi is the interactive shell. Per the official documentation, it is standalone: no configuration file, no service, no connection to a running daemon. You type SQL, rows come back, and when you exit, nothing persists. In the shipped packages it is the same underlying binary as the daemon (osqueryd invoked as a shell, which you can also do explicitly with osqueryd -S).

Two properties define its character. It runs with the privileges of whoever launched it, so an unelevated shell quietly sees less than the daemon does. And it is disposable by design, which makes it the right place to be wrong. Iterating on a clumsy JOIN in osqueryi costs nothing. The same mistake in a fleet schedule is an incident.

What is osqueryd?

Osqueryd is the daemon: a service (systemd on Linux, a Windows service, a LaunchDaemon on macOS) that runs a configured schedule of queries, each on its own interval, and writes results to whatever logger you configure. By default it logs differentially, only the rows that appeared or disappeared since the last run, which is what makes continuous monitoring affordable. It keeps state in a local backing store, which is also what lets evented tables like process_events buffer history between query executions.

The daemon also carries the safety equipment. A watchdog process monitors the query worker and restarts it when a query exceeds the default limits, roughly 10 percent sustained CPU for 12 seconds or 200MB of memory, documented in the command line flags reference. The shell has no watchdog. It assumes a human is watching, because one is.

What is actually different under the hood?

Both modes share the engine and the more than 270 tables, so a query that parses in one mode parses in the other. The differences are operational, and four of them bite in practice.

Privileges. Osqueryd typically runs as root or SYSTEM and sees everything its platform allows. Osqueryi sees what your user sees. An empty result in an unelevated shell is not evidence of absence, it is evidence you forgot sudo.

Events. Evented tables only accumulate inside a running daemon with the relevant subsystem enabled, audit or eBPF on Linux, EndpointSecurity on macOS. Query process_events in a fresh osqueryi session and you get nothing, not because events are broken but because nobody was listening. (Osqueryi can attach to an existing daemon's store with the --connect flag if you need to inspect buffered events interactively.)

Output. The shell prints tables to a terminal. The daemon emits JSON lines to the filesystem, a TLS endpoint, or syslog, and those results are only worth the disk they land on if something reads them. Which brings up state: the daemon's backing store tracks differentials per query, so results depend on what the last run saw. The shell has no memory at all.

One more operational difference: the daemon is a standing piece of infrastructure that needs patching like anything else. The project's 5.23.1 release in June 2026 fixed security issues in the agent itself. A forgotten osqueryi binary on a laptop is a curiosity; a fleet of outdated daemons running as SYSTEM is attack surface.

When should you use osqueryi vs osqueryd?

Use the shell when a human has a question now: an investigation, a compromise assessment, prototyping a detection, learning a table. Use the daemon when the question repeats. That is the entire decision rule, and the math on repetition is not subtle. An engineer who manually checks listening ports, new local accounts, and cron changes on a handful of servers each morning spends maybe 15 minutes a day. Over 250 working days that is 62 hours a year of skilled labor doing what a three query schedule does for free, without sick days, on every host instead of a handful.

The failure modes are symmetric. Shell only means visibility exists solely when someone is curious, which is never at 3am when the cryptominer starts. Daemon only, without shell prototyping first, means untested queries shipped across the fleet, watchdog restarts, and log volume nobody sized. The teams that get this right treat osqueryi as their staging environment, and the promotion path runs through a pilot group before the fleet, as we outline in the installation guide.

What does the split look like during a real incident?

A concrete scenario shows why you want both modes mature. An alert fires: outbound traffic from a build server to an address nobody recognizes. The responder opens an elevated osqueryi session on the host and asks the obvious questions in sequence. What is connected to that address (process_open_sockets joined to processes). Where did that binary come from (file and hash on its path). What launched it (the parent chain in processes). Does anything persist (crontab, systemd_units, startup_items). Fifteen minutes, no waiting on an agent vendor to add a feature, and every answer is a row with evidence attached.

The daemon's contribution happened before anyone was looking. Because osqueryd had process and socket events buffered, the responder can also see what ran an hour ago, not just what runs now. And because the fleet shares one schedule, one more query answers the question that decides whether this is a bad evening or a bad month: how many other hosts show the same binary hash. The shell gives depth on one machine. The daemon gives breadth across all of them, plus history. Investigations need all three axes, which is why the two modes are a system rather than a choice.

Afterward, the queries the responder typed by hand are candidates for the schedule. Every incident should leave the daemon config slightly better than it found it. That review habit belongs in the same postmortem that produces the incident report, and it costs ten minutes while the queries are still in shell history.

How do you promote a shell query to the daemon?

A query that earned trust interactively moves into the schedule as a named entry with an interval:

Three promotion habits pay off. Name the query for the question it answers, because that name is what you will see in logs and in the osquery_schedule performance table. Choose the interval from how fast the answer changes, not from enthusiasm. And write down what should happen when the query returns a row, because a detection without a response plan is a future ignored alert. Our guide to writing osquery queries covers the constraint and interval decisions in detail.

Promotion is also where organizational ownership gets decided, and skipping that decision is how schedules rot. Every scheduled query should have an owner who can say why it exists, and a quarterly config review should delete the ones nobody claims. A schedule is a living detection surface, not a config file you wrote once in a sprint and archived. Teams that prune ruthlessly keep signal quality high enough that people still read the results a year in, which is the entire point of collecting them.

How do you debug osqueryd when the daemon misbehaves?

The daemon's failure modes are quiet, which is the price of being unattended. Three techniques cover most diagnoses, and all three lean on the shell side of the house.

Run the daemon in the foreground. osqueryd --verbose in a terminal, with your production flags, shows config parsing, schedule registration, and event publisher status in real time. Config errors that a service manager swallows are obvious in ten seconds of foreground output. This is the first move when a new config deploys and nothing appears in the logs.

Query the daemon about itself. The osquery_schedule table reports per query executions, wall time, and output size, which identifies the expensive query behind watchdog restarts. The osquery_events table shows whether event publishers are actually active, the fastest way to discover that audit is claimed by another agent or that the macOS Full Disk Access grant never happened. An osqueryi session with --connect can inspect the live daemon's state directly.

Reproduce scheduled queries interactively before blaming the daemon. An elevated shell running the exact query from the config separates "the query is wrong" from "the daemon is wrong" in one step. In practice the query is wrong far more often, usually a privilege or scoping assumption that held on the test host and not on the fleet.

Frequently asked questions

Can osqueryi and osqueryd run at the same time?

Yes. They are independent processes and do not conflict. The one caution is state: a plain osqueryi session has its own empty store, so evented and differential behavior will not match the daemon unless you connect to the daemon's socket with --connect.

Does osqueryi need osqueryd installed or running?

No. The shell is fully standalone, which is why it is the fastest way to evaluate osquery. Download, run, query, delete, no service footprint.

Why does the same query return different results in each mode?

Almost always privileges (the daemon runs elevated, your shell may not), events (only the daemon accumulates them), or differential logging (the daemon reports changes, the shell reports current state).

Do I need a fleet manager to run osqueryd?

Not to start. A local config file on a handful of hosts works fine. Past a few dozen machines, a fleet manager pushing config over TLS becomes the practical requirement, because editing JSON by hand across a fleet is how schedules drift and coverage quietly rots.

Is osqueryd heavy on endpoints?

With the watchdog on defaults and a sane schedule, the daemon idles at a fraction of a percent of CPU and under 200MB of memory. Nearly every horror story traces to an unconstrained query or an event subsystem flooding on a busy host, both visible in osquery_schedule and both fixable.

The takeaway

Learn in the shell, operate in the daemon, and make the promotion path between them a habit rather than a project. If your team has only ever run osqueryi, pick your three most repeated questions this week and schedule them. If you deployed osqueryd without shell time first, open osqueryi tomorrow and test what you shipped. Either way the agent ends up doing the repetitive looking, people end up doing the deciding, and the deciding is the part worth an expensive brain. Reading the flood of rows the daemon produces is its own problem, and it is the one Artemes AI exists to solve: an AI engine that reads endpoint telemetry in context and surfaces the findings that deserve a human.