Connections
A Connection is a credential DreamLake holds on a namespace's behalf to reach another system — an S3-compatible bucket, a Hugging Face account, a Dropbox. Sources use one to read an external layer. A Connection is not a Lakeshore connection, and it is not how a computer joins DreamLake (host enrollment).
Only the namespace's credential managers (a personal namespace's owner, an
organization's owners) can see or change its Connections. Everyone else gets
not found, for the namespace's Connections and for any id. These commands use
your signed-in user token; machine and service-account credentials cannot manage
Connections, and agent service accounts cannot be granted one.
Secrets travel one way: in. No command prints a credential back, and none accepts one as a command-line argument.
Find out what this server accepts
What can be connected — connector kinds, their auth kinds, the inputs each asks for, and product or profile choices — is declared by the server, per deployment. Ask it rather than assuming:
Each row is one connector and auth kind. mode is how a credential arrives:
| mode | What it means | How to create |
|---|---|---|
fields | Typed inputs, some of them secret | dl connection create with a credential file or stdin, or dl connection entry create |
oauth | Browser sign-in at the provider | dl connection oauth create |
none | No credential, possibly some configuration | dl connection create --no-credential |
Inputs marked * go in the credential; the rest go in private configuration.
--json adds labels, select options and conditional requirements (for
example, an S3 region required only for some profileId values). S3 offers
an access key auth kind (access key id, secret, optional session token) and,
for the aws profile only, a role auth kind (a role ARN DreamLake assumes,
with an external id). Its profileId choices — such as aws, b2 or r2 —
are the profiles this deployment has configured; another server may offer
different ones.
Create one from a file or stdin
The server validates the credential before it creates the Connection; a refusal creates no Connection. Delete the credential file afterwards.
For the role way in, roleArn is configuration and externalId is the secret:
The role's trust policy must already allow DreamLake's AWS identity to assume
it, with an sts:ExternalId condition equal to externalId, and the role needs
read access to the buckets you will import. The CLI does not show that
identity; get it from whoever operates your DreamLake deployment. --idempotency-key reuses the key of an
attempt that never answered, so a retry cannot create a second Connection.
Hand entry to the web form
When the secret should not touch this machine, start a browser entry instead. The link carries only an opaque id. Finish it yourself, signed in to the web app as the same user who started it: it works for no one else, only in that namespace, for 30 minutes, and only once.
Open the printed link while signed in, choose the product, and enter the
credential there. entry status then reports succeeded with the Connection id
and its masked details, or pending, cancelled or expired. The connector and
auth kind are fixed by the entry; the label is a suggestion you can change.
Only fields auth kinds use an entry. dl connection entry reconnect <id>
does the same for a new credential on an existing Connection, at the revision
it was started from.
The DreamLake assistant uses the same entry when you ask it to connect storage: it gives you the link and reads the result, and never sees the credential.
Manage
check probes a Connection without changing it. available means the provider
accepted the credential at the Connection's endpoint; it says nothing about a
particular bucket. unverified (reason target-required) means this way in has
no check that works without a target. Bucket and prefix access is checked when
you import a Source.
Each change reads the current revision first and is refused if someone changed
the Connection in between. delete is refused while a Source still uses the
Connection — affected-sources lists them. OAuth Connections reconnect with
dl connection oauth reconnect.
Use it from a Source
The Connection decides the endpoint profile; the target names only the bucket and prefix. See Sources.
TypeScript
The same operations are on connections(namespace) in
@dreamlake/dreamlake-cli/api, with typed results:
create, rename, reconnect, enable, disable and delete take an
idempotency key as their last argument. All but create also take the
settings revision you last read; a changed Connection refuses the call.