Connections

A connection is a server plus a credential, registered once, under a name of its own. Steps point at it by name — never at a host and a password written inside the flow.

It is what separates "this agent talks to the ERP" from "this agent carries the ERP password".

The five types

Type	For	Used by
http	an API with a base address and authentication	Call an API
postgres	a relational database	Query a database
smtp	a mail server	Send email
ssh	a registered machine	Run over SSH · SFTP
s3	S3-compatible storage	Read and write files

Each connection lives in an Agent Space and belongs to the organization. The name is unique per type within the space: you can have finance as postgres and finance as smtp, and they are distinct things.

The credential goes in once and does not come back

you type it  →  secret vault  →  the step receives a REFERENCE

What the connection stores are the non-secret fields: host, port, user, base address. The secret goes to the vault and the connection keeps only a pointer.

Consequences you will notice:

• when you edit a connection, the password field is empty. That is not a bug: the value is not retrievable for display. Leave it blank and it stays what it was; fill it in and it is replaced;
• what is written into the agent's definition is the reference, never the value. A published version carries no credential;
• the conversation with Imaginne cannot reach it either: what exists there is the connection name. If anyone asks for the password in the conversation, the right answer is to open the screen — and that is what it does.

Testing connects for real

The Test button does not check the form: it opens the actual connection.

Type	What the test does
smtp	STARTTLS and authentication
postgres	a SELECT version()
s3	a listing
ssh	runs a trivial command
http	a probe against the base address

A passing test proves the credential works now. That is the difference between finding the problem here and finding it on the first scheduled run, at 3 a.m.

In the step

When a step has a connection selected, the fields the connection already answers disappear from the panel — host, port, user, base address. They are not filled in and greyed out: they are gone. Two places to say the same thing is how the two drift apart.

The connection picker is inside the step itself. You do not have to leave for the connections page to choose one.

What publishing refuses

Validation runs before a version exists, and it refuses:

• a step pointing at a connection that does not exist in the space;
• a connection of the wrong type for that step — an smtp on a database step;
• a credential written inside the step, when the field would accept a connection.

Refusing at publish time is deliberate: a flow that only fails on its first execution has already become an immutable version and is already live.

SSH: the server's key is pinned

An ssh connection stores the host key of the registered machine, and the executor requires exactly that key, of the same type.

If the server presents a different key — because it was rebuilt, or because it is not the same server —, the connection is refused instead of proceeding. That is the behaviour you want: a machine swapped mid-route does not get your credential.

Register the key of the right type

The type of the registered key (ed25519, ecdsa, rsa) is pinned along with it. A server presenting a legitimate key of another type is refused, because nothing distinguishes that case from an improper swap.

Who can do what

Connections are governed by the Agent Space, like everything else:

Role	View	Create and edit	Use in a step
creator	✅	✅	✅
publisher	✅	✅	✅
admin	✅	✅	✅

What separates the environments is not the role: a production-only secret is blocked in development. See Concepts.

Next steps

• Call an API
• System components
• Enabled resources