Secure Agent
Connect data sources that live inside your private network to DataKnits — without opening a single inbound firewall port, exposing a database to the internet, or setting up a VPN. The Secure Agent runs inside your network and reaches out to DataKnits, never the other way around.
Overview
Many organizations keep databases, file servers, and internal systems on a private network with no direct path in from the internet — and for good reason. The Secure Agent lets DataKnits work with that data anyway, without asking you to weaken that boundary.
Instead of DataKnits reaching in to your network, you install a small piece of agent software on a machine inside your network. That agent reaches out to DataKnits over a standard outbound connection — the same direction your browser already uses to reach any website. Your firewall stays exactly as closed as it is today; nothing needs to listen for inbound traffic, and no port needs to be opened on your side.
How It Works
- You register the connection as On-Premises. When you create a connection to a database or system that lives inside your network, you mark its deployment location as "On-Premises" instead of "Cloud".
- An administrator provisions an agent. The administrator gives the agent a name and chooses which on-premises connection(s) it is allowed to work with.
- The administrator installs the agent inside your network. DataKnits provides one-time setup credentials and installation instructions. The administrator installs the agent on a machine inside your network that can reach the systems it needs to work with, and starts it using those one-time credentials.
- The agent connects outbound and checks in. The agent opens a connection out to DataKnits (never the reverse) and identifies itself using the one-time credentials it was started with. Once verified, it shows up as an active agent.
- Work is dispatched to the agent, not the other way around. When you want to move data, you tell DataKnits which on-premises table to read and which cloud destination to send it to. The agent picks up that instruction on its outbound connection, reads the data locally, and streams it out in batches to the destination — your source system is never exposed directly to the outside.
Prerequisites
- Administrator access to DataKnits (agent provisioning requires admin permissions).
- A machine inside your private network that can reach the on-premises system(s) you want to connect (for example, the same network segment as your database server).
- That machine must be able to make outbound connections to DataKnits over HTTPS. No inbound rule, port forwarding, or VPN is required.
- The connection details (host, credentials, etc.) for the on-premises system you want the agent to work with, already entered into DataKnits as a connection.
Setting Up an Agent
Step 1 — Register the on-premises connection
- Go to Connections and click New Connection.
- Pick the technology (database, file server, etc.) and enter its connection details as usual.
- Under Deployment location, choose On-Premises instead of Cloud.
Step 2 — Provision an agent
- Go to Settings → Agents.
- Click Provision Agent.
- Give the agent a descriptive name (for example, the site or data center it will run in).
- Select the On-Premises connection(s) this agent should be allowed to work with.
- Click Provision Agent to confirm.
Step 3 — Save the one-time setup credentials
Immediately after provisioning, DataKnits displays a one-time setup key and a configuration bundle for this agent, along with the exact command to install and start it.
Step 4 — Install and start the agent
- Copy the install command DataKnits generated for this agent.
- Run it on the machine inside your network that will host the agent.
- The agent starts, connects outbound to DataKnits, and verifies itself using the one-time setup key.
Step 5 — Confirm the agent is active
Back in Settings → Agents, the agent's status changes to Active once it has successfully checked in, and its Last Seen timestamp starts updating. It is now ready to receive work.
Running Work Through the Agent
With an active agent in place, you can move data from its assigned on-premises connection(s) to a cloud destination:
- In Settings → Agents, find the active agent and click Run Job.
- Choose the on-premises source connection and the table to read (and, optionally, a filter to limit which rows are read, plus the batch size to send at a time).
- Choose the cloud destination connection and target table.
- Click Run Job. The table name, filter, and destination are sent to the agent at this point — nothing about the job is pre-loaded onto the agent at install time.
Expand Jobs under the agent to watch progress live: status (Pending, Running, Done, or Failed), batches and rows sent by the agent, and rows written at the destination. The view refreshes automatically while a job is running.
Managing Agent Lifecycle
| Action | Effect |
|---|---|
| Deactivate | Temporarily suspends the agent. It stops being able to receive work until it is reactivated. Use this for planned maintenance windows. |
| Activate | Re-enables a deactivated agent. |
| Revoke | Permanently and immediately disables the agent. This cannot be undone — provision a new agent if access is needed again. |
You can run multiple agents at the same time — for example, one per data center or one per on-premises network segment — each scoped to only the connections it was provisioned with.
Network & Security
- Outbound-only. The agent always initiates the connection to DataKnits. Your firewall does not need any inbound allow-rule, port forwarding, or public IP for the agent to work.
- No standing exposure. On-premises systems connected through an agent are never reachable directly from DataKnits or the internet — only the agent, running inside your network, talks to them.
- Scoped access. Each agent can only work with the specific connection(s) it was provisioned with — not every on-premises connection in your organization.
- One-time setup credentials. The credentials used to bring an agent online are shown once at provisioning time and are not retrievable afterward.
- Instant revocation. Revoking an agent immediately and permanently cuts off its access — no need to change network configuration on your side.
Troubleshooting
| Symptom | Likely cause / fix |
|---|---|
| Agent status stays "Inactive" and Last Seen shows "Never" | The agent hasn't successfully checked in yet. Confirm the machine running it has outbound HTTPS access to DataKnits, and that the install command was run with the setup key and configuration bundle exactly as copied. |
| "No ON_PREM connections found" when provisioning | No connection has been marked On-Premises yet. Create or edit a connection and set its Deployment location to On-Premises first. |
| Run Job dispatches but stays "Pending" | Check that the target agent's status is Active — a deactivated or revoked agent will not pick up new jobs. |
| Job fails | Check the job's error details in the Jobs panel — most failures trace back to the source table name, filter, or destination table not matching what actually exists. |
FAQ
Does DataKnits ever connect into my network?
No. The agent always makes the outbound connection. DataKnits never initiates a connection to a machine inside your network.
Can one agent access more than one on-premises system?
Yes — an agent can be provisioned with more than one On-Premises connection, and can be used for jobs against any of them.
What happens to in-flight work if I revoke an agent?
Revocation immediately and permanently blocks the agent from being used for further work.
Can I run more than one agent?
Yes, you can provision and run as many agents as you need — for example, one per site or data center.